Scope reference

A scope is the smallest unit of "what this token is allowed to do". When you request a token, you list the scopes you need; the platform issues a token that carries exactly that list (or fewer, if the user / application is not entitled to everything you asked for).

This page lists the scopes that ship with IntelliAuth by default. Tenants can also define their own.

The OpenID Connect scopes

These four are standard across every OIDC provider.

Scope	What it includes in the id token
openid	The bare minimum. Without it, the platform does not treat the request as OIDC — no id token is issued. Always include openid if you want OIDC at all.
profile	name, given_name, family_name, preferred_username, picture, locale, updated_at.
email	email and email_verified.
offline_access	Asks the platform to issue a refresh token alongside the access token. Without this scope, the token response has no refresh_token field.

openid profile email offline_access is the common starter set for a typical web app: identity + name + email + the ability to silently refresh.

IntelliAuth API scopes

These let an application call the platform's own APIs. The exact set available to your application is configured in the application's settings; if you request a scope that is not on the allowed list, the platform refuses with invalid_scope.

The shape is <resource>:<verb>. The resources roughly map to entities you can administer through the API.

User-oriented (called by the user's own SDK)

Scope	Meaning
me:read	Read the current user's profile (the /api/v1/me/profile surface).
me:write	Update the current user's profile, change password, manage MFA enrolments.
me:sessions	List and revoke the current user's own sessions.

Admin-oriented (called by trusted backends or admin UIs)

Scope	Meaning
users:read	Read user records in this tenant.
users:write	Create / update / delete user records in this tenant.
groups:read	Read groups and group memberships.
groups:write	Manage groups and memberships.
applications:read	Read application configurations.
applications:write	Manage applications, including credential rotation.
audit:read	Read the audit feed.

Resource / ReBAC

Scope	Meaning
resources:read	Read resources and their relationships (the ReBAC surface).
resources:write	Create / update / delete resources and relationships.

What goes into a token

When you ask for openid profile email users:read:

• The scope claim in the access token is openid profile email users:read.
• The id token carries name, given_name, family_name, etc. plus email, email_verified.
• The access token grants users:read on the tenant's API.

API gateways and resource servers verify the access token's scope claim and enforce per-endpoint requirements. An endpoint requiring users:write rejects a token with only users:read.

Least privilege

Request the narrowest set you need. Three reasons:

1. Defence in depth. A leaked token is bounded by its scopes; a narrow token is less dangerous.
2. Consent screens. Users see what your app is asking for. Asking for less builds trust.
3. Token size. Some platforms include scopes as a comma-separated list in cookies or headers; narrower scopes mean smaller tokens.

A common mistake is requesting users:write "just in case". Don't. If a code path doesn't need it, the token shouldn't carry it.

Custom scopes

Tenants can define their own scopes for their own APIs. Conventionally these follow the same <resource>:<verb> shape, namespaced by the API:

• accounts:read, accounts:write for an internal accounts API.
• payments:initiate, payments:approve for finer-grained payment authority.
• payroll:export for a one-off scope on a specific operation.

Custom scopes are managed in the tenant admin console; once defined, applications can be granted them and ask for them at /oauth2/authorize.

The openid requirement

Worth restating: if you want OIDC (id token + userinfo + claim plumbing), you must include openid in your scope list. Without it the platform treats your request as plain OAuth 2.0 — you get an access token but no id token. This is usually not what you want for a sign-in flow.

See also

• Audiences and scopes
• Authorization code with PKCE — for web apps
• Authorization — RBAC and ReBAC