I IntelliAuth Docs

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