Auth Tokens

Auth Tokens API

Overview

The Auth Tokens API mints identity tokens. An identity token is a short-lived, single-use credential that your backend mints for an existing end user. Your client passes the token to the Messaging SDK as identityToken. The SDK exchanges the token automatically and starts the session as that end user.

This API allows integrators to:

  • Identify end users in Messaging sessions. Use POST /v2/auth/tokens/ to mint a token for a known end_user_id, then pass it to the Messaging SDK.
  • Carry one conversation across devices. The token binds the session to the end user, not to a device. Each device exchanges its own freshly minted token and restores the same conversation.
  • Keep long-lived credentials off the client. Your API key stays on your backend. Only the short-lived identity token reaches the browser or app.

For the exchange flow and the SDK configuration, see the identity tokens overview.

Authentication

POST /v2/auth/tokens/ authenticates with your API key as a Bearer token, like all other v2 Platform APIs. See Authentication.

Call the endpoint from your backend only. The API key must never reach a browser or mobile app.

Token lifetime and use

Identity tokens follow strict lifecycle rules:

  • Single use. One exchange consumes the token. The exchange rejects a reused token, and the session falls back to anonymous.
  • Short-lived. Every token expires 15 minutes after minting. The expires_in field reports the lifetime in seconds and is always 900.
  • One end user. Each token represents one existing end_user_id. Mint a fresh token for every device and every session.

The token is a JWT that carries Ada identity references only. Treat it as opaque. Do not parse it or depend on its contents.

Successful responses return 201 with Cache-Control: no-store, no-cache, so intermediaries do not cache the credential.

Rate limits

POST /v2/auth/tokens/ applies these rate limits per AI Agent:

  • Requests per day: 1,000,000
  • Requests per minute: 1,000
  • Requests per second: 100

The limits are sized for one mint per end user who opens chat. A 429 response means your requests exceeded a limit. Back off and retry. See also the global rate limits.

Security handling rules

Treat an identity token like a password for the end user it names:

  • Mint tokens on your backend only.
  • Deliver tokens to the client over HTTPS only.
  • Never place a token in a URL, query parameter, or deep link.
  • Never log tokens, on the server or in the client.
  • Mint a fresh token per device and per session. Never reuse or pre-mint tokens.
  • Before you mint identity tokens, create end users with the End Users API. You can also use it to look up existing end users by your own external_id.
  • Use the Messaging SDK identity guides to pass the token to each platform SDK.