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
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
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
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
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
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"
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.