Scope reference

Wiring in flight. The scope catalogue below reflects the v2 surface. A handful of scopes for surfaces still on v1 may appear as duplicates or under transitional names during this quarter; we're collapsing them as features land.

A scope is the wire format of a capability. When a role's capability is "Read transactions", the token carries scope: payments:read. APIs receiving the token validate the scope claim.

The scope catalogue is the tenant-wide list of legitimate scope strings. When you build a role's capabilities, you're picking from this catalogue.

OIDC standard scopes

Every tenant ships with the four OIDC standards:

Scope	What it grants
openid	Required for any OIDC flow. Issues an id token alongside the access token.
profile	Adds name, given_name, family_name, picture, locale to the id token + userinfo.
email	Adds email + email_verified.
offline_access	Requests a refresh token alongside the access token.

You don't add these to custom roles — they're handled at the application's allowed-scopes list, requested by the application at sign-in.

IntelliAuth API scopes

These let an application (or, indirectly, a user via a role) call platform APIs. Shape: <resource>:<verb>.

Self-service (me:*)

For a user's own account.

Scope	Grants
me:read	Read own profile, sessions, MFA factors.
me:write	Update own profile, change password, manage own MFA.
me:sessions	List + revoke own sessions.

Admin-side users

Scope	Grants
users:read	Read user records in this tenant.
users:write	Create / update / disable / delete users.
users:bulk	Bulk import + export.

Admin-side applications

Scope	Grants
applications:read	Read application configs.
applications:write	Create / update / disable / delete applications.
applications:rotate-secret	Rotate client secrets.

Groups + roles

Scope	Grants
groups:read	Read groups + memberships.
groups:write	Manage groups + memberships.
roles:read	Read role definitions + assignments.
roles:write	Manage roles + assignments.

Audit

Scope	Grants
audit:read	Read the audit feed.
audit:export	Bulk export audit entries.

Resources (ReBAC)

Scope	Grants
resources:read	Read resources + relations + check authorisation.
resources:write	Create / update / delete resources + relations.

Federation

Scope	Grants
federation:read	Read federation connections.
federation:write	Manage federation connections (OIDC + SAML).

Webhooks

Scope	Grants
webhooks:read	Read webhook subscriptions + delivery history.
webhooks:write	Manage webhook subscriptions.

Out-of-scope (deliberately)

These don't have integrator scopes because the surfaces are tenant-admin web-only:

• Flows + Actions configuration
• Threat intelligence feed management
• Reports configuration
• Branding
• Breach incident management (read / resolve)
• Audit configuration (streaming setup; not reading)

Integrators receive webhook events for downstream reaction; the configuration itself stays in the admin console.

Custom scopes (for your own APIs)

Your applications likely talk to your own backend APIs, not just the platform's. The platform supports tenant-defined custom scopes for that surface.

Roles & scopes → Scope reference → New scope.

Define:

• Name — payments:read, inventory:write, analytics:export. Conventional shape is <resource>:<verb>; the platform doesn't enforce it but consistency pays off.
• Description — what your API treats this scope as granting.
• Category (optional) — for grouping in the picker UI.

Save. The scope is available for:

• Role capability assignment.
• Application allowed-scopes list.
• Bulk imports + management API operations.

How scopes flow at runtime

1. A user with role X has capabilities in role X.
2. Capabilities resolve to scope strings.
3. On sign-in, the application requests a token with scope: openid profile email <custom-set>.
4. The platform intersects: requested scopes ∩ application's allowed scopes ∩ user's capabilities.
5. The resulting scope set becomes the token's scope claim.
6. Your API validates the scope claim before serving each request.

The most-restrictive of the three sets wins. An application can't request what it isn't allowed to request; a user can't be granted scopes their roles don't cover.

Naming conventions

Conventions that pay off:

• Lowercase — payments:read, never Payments:Read.
• <resource>:<verb> — be consistent across your tenant.
• Avoid * — payments:* looks tidy but obscures intent. Define the specific verbs you need.
• One concept per scope — payments:approve not payments:approve-and-export. Split when the verbs are separable.

The platform doesn't enforce these; picking and applying a convention saves your future self.

What the platform refuses

• Scope name with whitespace — scope strings are space-delimited on the wire; whitespace inside one would break parsing.
• Scope name starting with @ — reserved for platform-internal scopes.
• Scopes deleted while still in use — the platform refuses deletion if any role or application still references the scope. Remove the references first.

See also

• Roles overview
• Per-app scopes
• Scope reference (developer reference)