> ## Documentation Index > Fetch the complete documentation index at: https://doc.extole.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /api-reference/integration-server-to-extole.json post /v4/tokens openapi: 3.0.1 info: description: >- Server-to-Extole integration endpoints: event submission, person lookup, zone rendering, token management, and reward retrieval for backend services authenticating with client credentials. title: Integration API - Server to Extole version: '1.0' servers: - description: Production url: https://api.extole.io security: - HEADER: [] - QUERY: [] - COOKIE: [] tags: - name: Authentication - name: Batch Jobs - name: Events - name: Files - name: Persons - name: Reward Suppliers - name: Rewards - name: SFTP Servers - name: Zone Rendering paths: /v4/tokens: post: tags: - Authentication summary: Create access token description: >- 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`. operationId: createClientAccessToken requestBody: content: application/json: example: client_id: client_id duration_seconds: 1 email: email password: password scopes: - BACKEND schema: $ref: '#/components/schemas/AccessTokenCreationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AccessTokenResponse' description: Access token created. '400': content: application/json: examples: invalid_client_id: $ref: '#/components/examples/invalid_client_id' invalid_duration: $ref: '#/components/examples/invalid_duration' schema: $ref: '#/components/schemas/RestExceptionResponse' description: >- 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': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: invalid_credentials: $ref: '#/components/examples/invalid_credentials' missing_credentials: $ref: '#/components/examples/missing_credentials' scopes_denied: $ref: '#/components/examples/scopes_denied' schema: $ref: '#/components/schemas/RestExceptionResponse' description: >- 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': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests components: schemas: AccessTokenCreationRequest: description: >- 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. properties: client_id: description: >- 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. type: string duration_seconds: description: >- 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`. format: int64 nullable: true type: integer email: description: >- Email address of the dashboard user to authenticate. Pair with `password`. Returns `403 invalid_credentials` if the pair is wrong. nullable: true type: string password: description: >- 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. nullable: true type: string scopes: description: >- 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. items: description: >- 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. enum: - BACKEND - CLIENT_ADMIN - CLIENT_REPORT_DOWNLOAD - CLIENT_SUPERUSER - ONE_TIME - PASSWORD_RESET - UPDATE_PROFILE - USER_SUPPORT - VERIFIED_CONSUMER type: string nullable: true type: array uniqueItems: true required: - client_id - duration_seconds - email - password - scopes type: object AccessTokenResponse: description: >- 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. properties: access_token: description: >- Token string. Send as `Authorization: Bearer ` on subsequent requests, or as the `access_token` query parameter / `extole_token` cookie. type: string client_id: description: >- Stable Extole identifier for the client (tenant) this token authenticates against. type: string expires_in: description: >- 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. format: int64 type: integer identity_id: description: >- Stable Extole identifier for the identity (user, managed identity, or resource) that this token represents. type: string person_id: deprecated: true description: >- Deprecated alias for `identity_id`. New integrations should use `identity_id`. type: string scopes: description: >- Authorization scopes granted to this token. Determines which API operations the token may invoke. items: description: >- Authorization scopes granted to this token. Determines which API operations the token may invoke. enum: - BACKEND - CLIENT_ADMIN - CLIENT_REPORT_DOWNLOAD - CLIENT_SUPERUSER - ONE_TIME - PASSWORD_RESET - UPDATE_PROFILE - USER_SUPPORT - VERIFIED_CONSUMER type: string type: array uniqueItems: true type: description: >- Authentication shape backing the token. `USER` represents a human dashboard user, `MANAGED` an OAuth-style managed identity, and `RESOURCE` a scoped per-resource token. enum: - MANAGED - RESOURCE - USER type: string type: object RestExceptionResponse: description: Represents the API error response properties: code: description: Specific error code for this error type, documented per endpoint type: string http_status_code: description: >- HTTP status code that was returned with this error, useful if client get response code format: int32 type: integer message: description: User readable English description of the error type: string parameters: additionalProperties: description: >- Attributes related to the error, varies be error code, documented per endpoint type: object description: >- Attributes related to the error, varies be error code, documented per endpoint type: object unique_id: description: >- Unique id associated with this error, useful for discussions with Extole type: string required: - code - http_status_code - message - parameters - unique_id type: object examples: invalid_client_id: summary: invalid_client_id value: code: invalid_client_id http_status_code: 400 message: Invalid client id parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_duration: summary: invalid_duration value: code: invalid_duration http_status_code: 400 message: >- The requested duration for this token must end within the first ten millenium parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 method_unauthorized: summary: method_unauthorized value: code: method_unauthorized http_status_code: 401 message: Unauthorized access to this endpoint parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 payment_required: summary: payment_required value: code: payment_required http_status_code: 402 message: The access_token provided is associated with an unpaid account. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_credentials: summary: invalid_credentials value: code: invalid_credentials http_status_code: 403 message: The credentials provided with this request are invalid. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 missing_credentials: summary: missing_credentials value: code: missing_credentials http_status_code: 403 message: No credentials provided with this request. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 scopes_denied: summary: scopes_denied value: code: scopes_denied http_status_code: 403 message: Requested scopes is not a subset of current scopes. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 unsupported_media_type: summary: unsupported_media_type value: code: unsupported_media_type http_status_code: 415 message: Request had an unsupported or no media type parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 too_many_requests: summary: too_many_requests value: code: too_many_requests http_status_code: 429 message: >- The server is unable to process your request at the moment, please retry later. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 securitySchemes: HEADER: in: header name: Authorization type: apiKey x-bearer-format: bearer QUERY: in: query name: access_token type: apiKey COOKIE: in: cookie name: extole_token type: apiKey ````