Why it matters
A role is a useful way to assign access, but the rule that matters is the permission check at each operation. As your product grows, fixed roles often need resource scope, custom roles or exceptions.
Permissions become a product contract: customers need to understand who can do what, and support needs to explain a refusal. Start with actions and scopes, then decide which roles package those permissions.
Decisions to make
- Name permissions around user actions rather than screens.
- Decide which scopes exist: account, organization, workspace or individual resource.
- Plan how permission changes reach long-lived sessions and cached decisions.
- Define whether a custom role can grant every permission or only a safe subset.
- Decide how permission changes invalidate cached decisions and active sessions.
Build checklist
- Enforce permissions on the server for reads and writes.
- Test allowed and refused actions for each role and scope.
- Show the effective access in admin UI so support can explain a refusal.
- Keep one documented permission matrix for each protected action.
- Test a user with access to one workspace attempting the same action in another.
Common mistakes
- Hiding a button while leaving its API action available.
- Encoding permissions in scattered role-name comparisons.
- Adding custom roles before the underlying actions and scopes are stable.
Tools & references
4 starting points to compare or study. Check fit, maintenance, terms and current capabilities before choosing one.