Wiring in flight. The v2 backend's role surface is being re-wired this quarter. Some screens in the admin console still display the v1 shape; some features (custom role creation, scope reference picker) are temporarily read-only. Operations that work today: viewing system roles, viewing role-to-user assignments, viewing the scope catalogue. Operations partially available: creating custom roles, assigning roles to groups. See per-topic callouts for specifics.
A role is a named bundle of capabilities. Roles let you say "Finance Admin can read transactions and approve payments" instead of granting each capability per-user. Add a user to the role; they inherit the bundle.
The two ways the platform delivers role-style access control:
- Roles assigned to users — straightforward. Anita gets the "Finance Admin" role.
- Roles assigned to groups — Anita is in the "Finance team" group; the group has the "Finance Admin" role; Anita inherits.
Group-based is usually the right pattern for organisations of any size — manage group membership in your HR system / identity source; the role assignment stays on the group.
What's NOT a role
Section titled “What's NOT a role”The platform doesn't have:
- Nested roles. A role can't contain another role. If you want "Senior Finance Admin = Finance Admin + extra capabilities", create both roles and assign both.
- Role hierarchies / inheritance. Roles are flat. No "this role inherits from that one".
- Time-bounded role assignments. A role assignment is permanent until you remove it. For temporary access, use group membership + a scheduled removal job.
These constraints are deliberate — they keep the model simple enough to reason about under fire. Most "I want hierarchy" needs map cleanly to "create separate roles."
Role vs capability vs scope
Section titled “Role vs capability vs scope”A small but important distinction:
- Capability — what the role can DO. "Read transactions", "Approve payments", "Manage applications". The conceptual unit you reason with.
- Role — a named bundle of capabilities. "Finance Admin".
- Scope — the wire format. Capabilities become scope strings (
payments:approve) on the access token. Your APIs check the scope claim.
You work with capabilities in the admin console; the platform translates to scopes for tokens. Your applications check scopes at the API boundary.
System roles
Section titled “System roles”Every tenant ships with a default set: Owner, Administrator, Operator, Viewer. See System roles for the full list and what each can do.
Custom roles
Section titled “Custom roles”Carve out tenant-specific roles: "Customer Success Lead", "Treasurer", "External Auditor". See Create a custom role.
When to define a role vs ad-hoc assignment
Section titled “When to define a role vs ad-hoc assignment”Use roles when:
- The same set of capabilities applies to multiple users.
- The capabilities will be revoked together when someone changes job.
- Auditors need to "show me everyone with finance-admin powers".
Skip roles when:
- One person has a unique capability set. Assign capabilities directly to their user (or a group containing only them).
- The capabilities are short-lived. Manage at the group level with a scheduled removal.
Reading "who has what"
Section titled “Reading "who has what"”The Roles surface answers two questions:
- Forward: "What can role X do?" — open the role; see its capabilities.
- Reverse: "Who has role X?" — open the role; see assigned users + groups.
For the user-side reverse ("what roles does Anita have?"), open Anita's user detail page; the Roles tab lists every role she has, directly or via group membership.