Create a custom role

Wiring in flight. Custom-role creation is operational; the capability picker reflects the v2 scope catalogue. Some capabilities not yet wired to v2 backends remain assignable but inert — they appear in the picker for forward-compatibility. Check the per-capability description for "available now" vs "wired in flight" markers.

System roles cover most needs. When they don't — a job that needs a non-standard mix — create a custom role.

Open the editor

Roles & scopes → New role.

Three sections:

Identity — name, description, internal slug.
Capabilities — what this role can do (the meat of the form).
Assignment — optional starter list of users or groups to attach.

Identity

Name — what tenant admins see ("Branding Editor", "External Auditor"). Keep it short and descriptive.
Description — what this role is for. Visible in the role picker; useful for the next admin who has to assign it.
Slug — URL-safe lowercase identifier. Auto-generated from the name; editable. Immutable once saved.

Capabilities — the catalogue

The catalogue groups capabilities by area:

Users — view / create / edit / suspend / delete / reset password / force MFA reset / bulk operations.
Applications — view / create / edit / rotate secret / disable / delete.
Authentication — configure policy / manage federation / edit flows / edit actions.
MFA — configure enforcement / manage custom factors.
Audit — read / export / configure streaming.
Threat intelligence — view / manage feeds / test IP.
Branding — view / edit.
Reports — view / configure.
Members — invite / change roles / remove.

Each capability has:

A name.
A short description ("Disable users without deleting their records").
A status flag — "available now" vs "wired in flight".

Pick what your role needs. Skip what it doesn't. Least privilege: it's easier to add a capability later than to audit why an old role has too many.

Assignment

You can pre-attach users or groups to the role at create time:

Users — pick from a search box. Multi-select.
Groups — pick from a search box. Multi-select.

Or skip — save the role, then assign later via the Assignment tab on the role's detail page (or from each user's / group's detail page).

Save

Click Create role. The role is live; assigned users gain the capabilities on their NEXT access token (next sign-in or next silent refresh; existing tokens carry the previous scope set).

The audit log records role.created with the role's name + slug + capability list + actor.

Examples — patterns that come up

"Branding editor"

A designer should manage the sign-in page's look but nothing else. Capabilities:

Branding → view + edit.
Members → (none — they don't manage other people).
Everything else → (none).

Assign to your design team's group.

"External auditor"

A contracted SOC 2 auditor needs read-only access scoped to specific audit queries. Capabilities:

Audit → read + export.
Users → view (so they can see who took an action).
Applications → view.
Authentication → view (policies, not edits).
Everything else → (none).

Time-bounded? Create the role, assign for the engagement, remove the assignment when the engagement ends. The role itself stays for the next engagement.

"Customer Success Lead"

A CS lead handles password / MFA recovery for paying customers. Capabilities:

Users → view + reset password + force MFA reset + suspend. NOT: delete, bulk operations, edit identities.
Audit → read (so they can confirm "yes this user has been signing in normally").
Everything else → (none).

This is the operational sweet spot for support staff who shouldn't have full Administrator powers.

"Compliance reviewer"

Similar to Viewer but with audit-export capability and group-membership visibility.

Audit → read + export.
Users → view.
Applications → view.
Branding → view.
Authentication → view.

Edit a custom role

Role detail page → in-place edit on each section. Save propagates: existing token holders pick up the new capabilities on their next refresh.

Caveat: REMOVING a capability from a role doesn't immediately downgrade existing tokens; they carry the previous capabilities until they expire. If you need immediate revocation (the user shouldn't have access RIGHT NOW), pair with bulk session revocation.

Delete a custom role

Role detail page → menu → Delete. Confirmation required.

What happens:

Every user / group assigned to the role loses the capabilities on their next refresh.
Audit records the deletion with the prior assignment list (for restoration if needed).
The role's slug is retired permanently — never reused.

You can't delete system roles; only custom ones.