---
title: "Create access token"
method: POST
path: "/v4/tokens"
tags: ["Authentication"]
---

# Create access token

`POST /v4/tokens`

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`.

## Request body

- AccessTokenCreationRequest — 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, 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`.
  - `email` string, nullable, required — Email address of the dashboard user to authenticate. Pair with `password`. Returns `403 invalid_credentials` if the pair is wrong.
  - `password` string, 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.
  - `scopes` string[], 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 `200`

Access token created.

- AccessTokenResponse — 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 — 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 alias for `identity_id`. New integrations should use `identity_id`.
  - `scopes` string[] — 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.

## Other responses

- `400` — Bad request. The named examples below cover this operation's input-validation errors. Other 400 causes include malformed JSON and missing required fields - inspect the response `code` field for the specific error.
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Authentication failed. The named examples below cover the most common credential rejections; other 403 causes (account locked, account disabled, requested scopes that exceed the calling identity's privileges) are auto-derived - inspect the response `code` field for the specific error.
- `415` — Unsupported Media Type
- `429` — Too Many Requests

---

[API](https://skmtc.net/extole/apis/integration-api-server-to-extole.md) · [All operations](https://skmtc.net/extole/apis/integration-api-server-to-extole/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/extole/integration-api-server-to-extole/revisions/c16e62e66755/schema)