Sign in

v1

latestOpenAPI 3.0.12026-07-244011,5573.5 MB
Authentication

Create access token

Mints a bearer token for server-to-Extole calls by a client. The body is optional: when omitted, the new token mirrors the calling identity's scopes; when supplied, the body can narrow the scope set (subset of the caller's scopes), bind the token to a specific client_id, supply email/password credentials in lieu of a calling token, or override the default lifetime via duration_seconds. Returns the new token, its expires_in (seconds), the resolved client_id, the identity_id of the user the token represents, and the granted scopes.

post/v4/tokens

Request body

client_idstring 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_secondsinteger nullable 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.

emailstring nullable required

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

passwordstring nullable 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.

scopesstring[] nullable 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.

Response

Access token created.

access_tokenstring

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

client_idstring

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

expires_ininteger

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_idstring

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

person_idstring

Deprecated alias for identity_id. New integrations should use identity_id.

scopesstring[]

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

type'MANAGED' | 'RESOURCE' | 'USER'

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