Skip to navigation
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 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.

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

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

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.