> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Auth Tokens API 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. Download full OpenAPI spec 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](/messaging/identity/overview). * **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](/messaging/identity/overview). ## Authentication `POST /v2/auth/tokens/` authenticates with your API key as a `Bearer` token, like all other v2 Platform APIs. See [Authentication](/reference/introduction/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 and optional encrypted handoff details. 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. ## Optional verified details Only your server sends `verified_email` and `name` in the mint request, alongside `end_user_id`. Use an email address whose ownership your system has verified. > **Warning** > > Ada links to or creates a Zendesk user from the email. > A wrong email links the conversation to another person's Zendesk user. > > [Read all risks](/docs/handoffs/zendesk/zendesk-messaging#authenticate-end-users) Ada carries both values encrypted in the identity token without storing them at mint. Ada stores the values encrypted on the session's end user. Ada uses them only in the first 7 days after the exchange. Ada deletes them after the first Zendesk Messaging handoff uses them and Sunshine initialization succeeds. If no handoff uses them, Ada deletes them at the next handoff or token exchange after the 7 days end. Session refresh does not extend this window. Without `verified_email` or `name`, mint, exchange, and handoff keep their existing behavior. Verified email linking needs an `external_id` on the end user. Create or look up the end user with an `external_id` through the End Users API. Without an `external_id`, Zendesk Messaging handoffs ignore the Ada identity token, `verified_email`, and `name`. When the mint request includes `verified_email`, Zendesk Messaging handoffs use it to link to or create your Zendesk end user. Ada uses this order: 1. Use the Zendesk end user with the same `external_id` as the Platform API identity mapping. 2. Otherwise, link exactly one Zendesk end user with a matching primary email. 3. If no match exists, create a Zendesk end user with the name and verified email. Ada uses `name` from the mint request first, then the end user's profile `first_name` and `last_name`. Ada trims the profile names and joins them with a space. If Sunshine initialization fails, Ada keeps the values for a retry. See [Authenticate end users](/docs/handoffs/zendesk/zendesk-messaging#authenticate-end-users) for the full matching rules. Expired sessions cannot supply these values. A new exchange replaces the previous linking values, including an exchange on another device. Tokens contain no plaintext email address or name. The linking fields are absent from API responses, end-user resources, and webhooks. When the exchanged token has decrypted claims, Ada updates `jwt_email` and `jwt_name` for display. A missing or empty value clears its previous display copy only if that copy still matches the value Ada wrote. Ada updates `name` only when it is empty or still equals the previous token's name. It never writes `email` from these claims. When Ada clears the linking values, including when it detects expiry, it also clears display copies that still match the values Ada wrote. Without claims, exchange clears the previous claims and display copies that still match the values Ada wrote. It does not use the profile name for display. Ada never reads those display copies for identity. Widget metadata and Capture blocks cannot change the linking values. See [Verified handoff details](/messaging/identity/overview#verified-handoff-details) for name fallback and display behavior. ## Rate limits `POST /v2/auth/tokens/` applies these rate limits per AI Agent: * No daily limit * 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](/reference/introduction/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. ## Related resources * Before you mint identity tokens, create end users with the [End Users API](/reference/end-users/overview). You can also use it to look up existing end users by your own `external_id`. * Use the [Messaging SDK identity guides](/messaging/identity/getting-started) to pass the token to each platform SDK.