Skip to main content
POST
Create access token

Authorizations

Authorization
string
header
required

Body

application/json

Optional body for POST /v4/tokens. Omit the body entirely to mirror the calling identity's scopes; supply a body to bind the new token to a specific client_id, narrow its scopes, override the default lifetime via duration_seconds, or authenticate with email/password credentials in lieu of a calling token.

client_id
string
required

Stable Extole identifier for the client (tenant) the new token should authenticate against. Required when authenticating with email/password credentials; optional when the calling identity already implies the client.

duration_seconds
integer<int64> | null
required

Override the default token lifetime, in seconds. Must keep the token's expiry within the next ten millennia; out-of-range values return 400 invalid_duration with the default lifetime in default_duration.

email
string | null
required

Email address of the dashboard user to authenticate. Pair with password. Returns 403 invalid_credentials if the pair is wrong.

password
string | null
required

Password for the dashboard user identified by email. Returns 403 invalid_credentials if wrong, 403 expired_credentials if expired, 403 account_locked if the account is locked, and 403 account_disabled if disabled.

scopes
enum<string>[] | null
required

Subset of the calling identity's scopes to grant on the new token. Must be a strict subset; requesting a privilege the caller does not hold returns 403 scopes_denied with the offending scopes in denied_scopes. Omit to mirror the caller's scopes.

Subset of the calling identity's scopes to grant on the new token. Must be a strict subset; requesting a privilege the caller does not hold returns 403 scopes_denied with the offending scopes in denied_scopes. Omit to mirror the caller's scopes.

Available options:
BACKEND,
CLIENT_ADMIN,
CLIENT_REPORT_DOWNLOAD,
CLIENT_SUPERUSER,
ONE_TIME,
PASSWORD_RESET,
UPDATE_PROFILE,
USER_SUPPORT,
VERIFIED_CONSUMER

Response

Access token created.

Access-token metadata returned by POST /v4/tokens, POST /v4/tokens/openid-connect/authorization-code-flow, GET /v4/tokens, GET /v4/tokens/{token}, and PUT /v4/tokens/exchange/{token}. Pass access_token in the Authorization header (Bearer ...) on subsequent requests.

access_token
string

Token string. Send as Authorization: Bearer <access_token> on subsequent requests, or as the access_token query parameter / extole_token cookie.

client_id
string

Stable Extole identifier for the client (tenant) this token authenticates against.

expires_in
integer<int64>

Seconds until this token expires. Once expired, requests using it return 401 invalid_access_token; rotate via PUT /v4/tokens/exchange/{token} before expiry to keep long-lived integrations alive.

identity_id
string

Stable Extole identifier for the identity (user, managed identity, or resource) that this token represents.

person_id
string
deprecated

Deprecated alias for identity_id. New integrations should use identity_id.

scopes
enum<string>[]

Authorization scopes granted to this token. Determines which API operations the token may invoke.

Authorization scopes granted to this token. Determines which API operations the token may invoke.

Available options:
BACKEND,
CLIENT_ADMIN,
CLIENT_REPORT_DOWNLOAD,
CLIENT_SUPERUSER,
ONE_TIME,
PASSWORD_RESET,
UPDATE_PROFILE,
USER_SUPPORT,
VERIFIED_CONSUMER
type
enum<string>

Authentication shape backing the token. USER represents a human dashboard user, MANAGED an OAuth-style managed identity, and RESOURCE a scoped per-resource token.

Available options:
MANAGED,
RESOURCE,
USER