Guides Reference

Permissions in your token

Your access token tells the API what you are allowed to do. This guide explains where that set comes from, the coarse access scopes that authorize the whole API by HTTP method, and the full fine-grained catalog a customer tenant can hold when you want a narrowly-scoped token instead.

Where your permissions come from

The permissions array in your access token (the claim https://cybersentriq.com/permissions) is the authoritative authorization set. Read it to decide what the caller may do.

It is the union of the permissions from your roles in the current organization and your app assignments. The set you actually hold is therefore a subset of the catalog below: the catalog is the full set a customer tenant can hold, not what any single caller receives.

permissions is distinct from the OAuth scope string. scope is what your client asked for when it obtained the token; permissions is what your roles and app assignments grant. For how the token is built and validated, see Authentication overview.

Two ways to scope a token

The coarse api:full:read / api:full:write scopes authorize the whole API surface by HTTP method — they are a superset, not a separate surface. api:full:read authorizes any read (GET, HEAD and QUERY); api:full:write authorizes any write (POST, PUT, PATCH, DELETE) and implies read. This is the simplest way to call the API: request both and you can exercise the whole surface.

The permission catalog below is the fine-grained, least-privilege model — what each role holds and the specific permission each endpoint accepts (for example, PATCH /self/profile accepts self:profile:write). Use it when you want a narrowly-scoped token instead of the coarse scopes.

The catalog

The permissions below are the full set. Which of them you hold depends on your role in the current organization.

Every user

Every signed-in user holds the self:* permissions: the actions on their own identity, including the writes. Managing your own profile, MFA, password, sessions and tokens is not an administrator privilege. Every user also holds read access to the organization profile.

Permission What it allows
self:profile:read Read the authenticated user's profile.
self:profile:write Update the authenticated user's profile.
self:sessions:read List the authenticated user's active sessions.
self:sessions:write Revoke the authenticated user's sessions.
self:mfa:read Read the authenticated user's multi-factor authentication settings.
self:mfa:write Enroll or remove the authenticated user's multi-factor authenticators.
self:password:write Change the authenticated user's password.
self:tokens:write Issue or revoke the authenticated user's API tokens.
self:organization:read Read the organization's profile and settings.

Account administrators

An account administrator holds everything above, plus the permissions to manage the organization, its users and its connections.

Permission What it allows
self:organization:sso:read Read the organization's single sign-on (SSO) configuration.
self:organization:sso:write Manage the organization's single sign-on (SSO) configuration.
users:account:read List and read the users in the organization.
users:account:write Create, update, and remove users in the organization.
users:mfa:write Manage multi-factor authentication for users in the organization.
connections:account:read List and read the organization's identity connections.
connections:account:write Create, update, and remove the organization's identity connections.
connections:audit:read Read audit records for the organization's identity connections.
m2m:credentials:read List the organization's machine-to-machine (M2M) API credentials.
m2m:credentials:write Create, rotate, and revoke M2M API credentials.

Coarse access scopes (day one)

Fine-grained, per-permission scoping is not yet available end to end. Until it is, request one or both coarse access scopes when you obtain a token. They authorize the whole API by HTTP method:

Scope What it grants
api:full:read Read across the full API: the safe methods GET, HEAD and QUERY.
api:full:write Write across the full API: the mutating methods POST, PUT, PATCH and DELETE. Implies api:full:read.

A read-only client requests just api:full:read. Request both when your integration also writes. The API grants a coarse scope only if your role allows it: account administrators get read and write; all other users get read.

You request these in the scope parameter of your token request. See Service account and M2M authentication and User and device-code authentication.

The coarse scopes are a stop-gap. Finer scopes will replace them as per-permission scoping lands, and code that requests the specific permission it needs will keep working. Request the coarse scope your integration needs now, and it stays correct as scoping tightens.

Next