Identity tokens

Identity tokens let your backend tell Ada, with proof, which end user is chatting. Your backend mints a short-lived, single-use token for a known end user. Your client passes it to the Messaging SDK. Ada exchanges it for an identified session before the conversation starts.

One identity means one conversation. The same end user gets the same conversation, with its history and live updates, on every device and browser where they sign in.

Without an identity token, Messaging sessions are anonymous. The AI Agent knows only what the browser or app stores locally, plus any metadata you pass.

Why use identity tokens

• One conversation on every device. The token binds the session to the end user, not to a device or browser. Each device exchanges its own token, restores the same conversation with its history, and receives live updates.
• Simpler than building a channel. The Conversations API also supports verified users, but it requires you to build and operate a full custom channel. Identity tokens add verification to the channels Ada already runs.
• Identity on your terms. Your backend decides who gets a token, using your own session and business logic. Ada never sees your credentials, and your authentication flow does not change.
• No repeated verification. An end user who is already signed in to your product is identified in chat automatically. They do not prove their identity again inside the conversation.
• Native speed and reliability. The conversation stays on Ada’s own web and mobile channels, with Ada’s realtime transport, persistence, and recovery. Nothing is proxied through your infrastructure.

How the exchange works

1. An end user signs in to your site or app. Your backend verifies them with your normal logic.
2. Your backend calls POST /v2/auth/tokens/ on Ada’s Platform API with the end user’s Ada id.
3. Ada returns an identity token: a JWT that expires in 15 minutes and can be used exactly once.
4. Your client passes the token to the Messaging SDK as identityToken.
5. When the end user engages with the chat, the SDK exchanges the token with Ada before it restores any saved conversation state.
6. Ada consumes the token and binds the session to that end user. The conversation proceeds as that identified user.

The exchange is a credential bootstrap. It does not merge existing conversations or reassign them between users.

One conversation across every device

Identity binds the conversation to the end user, not to a device. When the same end user signs in on another device or browser, repeat the flow:

1. Your backend mints a fresh token for the same end_user_id. Tokens are single use, so every device and every sign-in needs its own mint.
2. The new device passes its token to the SDK, which exchanges it as normal.
3. The exchange resolves to the same end user. The device restores the same conversation, with its message history, before the chat opens.
4. Every connected device shares the same realtime channel, so live updates reach all of them.

A new exchange does not sign out other devices. A signed-in laptop and a signed-in phone hold live identified sessions at the same time.

An automated end-to-end suite verifies this flow continuously against a live environment: two devices, two freshly minted tokens, one shared conversation.

See the two-device walkthrough for the concrete steps.

Token lifecycle rules

• Single use. Each token is consumed by one exchange attempt. The SDK clears it even when session creation fails afterward, so every attempt needs a freshly minted token. A new device or browser needs its own mint; never reuse a token.
• Short-lived. Tokens expire 15 minutes after minting. Mint on demand, close to the moment the client needs one.
• The server decides validity. The client always attempts the exchange, even when the local clock says the token looks expired. Only a server rejection fails the exchange.
• Failures are survivable. A rejected or expired token publishes the ada:identity_token:error event, and ada:identity_token:expired when the token had elapsed. The session then continues anonymously.
• Resets discard pending tokens. A full reset() without a replacement token discards any token that has not finished exchanging. Pass a new identityToken to reset() to identify again.
• Identified sessions are isolated. Identified auth state is scoped per tab and bound to the token’s subject. Two tabs signed in as different users cannot read or overwrite each other’s credentials.

Platform support

On mobile, the SDK injects the token into the WebView document before any page script runs. The token never appears in any URL, and the runtime deletes it from the page after one read.

Verified handoff details

Your server can send optional verified_email and name fields with end_user_id when it mints an identity token. Send these fields only from your server to POST /v2/auth/tokens/. Use an email address whose ownership your system has verified.

name is the end user’s name.

Ada removes surrounding whitespace from both fields. The email must be valid and contain at most 254 characters after trimming. The name must be a string with at most 255 characters after trimming. Invalid values return 400 before Ada stores anything. Omit either field when you do not need it.

Ada carries these values encrypted in the identity token without storing them at mint. The token contains no plaintext email address or name.

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. If name is empty or absent, Ada trims the profile first_name and last_name and joins them with a space. If both are empty, Ada uses the verified email as the name when it creates the Zendesk end user.

If Sunshine initialization fails, Ada keeps the values for a retry. Without a verified email, the handoff uses the Platform API identity mapping without a Zendesk user lookup. 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.

When the exchanged token has decrypted claims, Ada updates the display copies jwt_email and jwt_name. 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. This preserves a name that your page or a Capture block sets. Ada does not copy the verified email into the dashboard’s email value. 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 these display copies back for identity.

The linking fields are absent from API responses, end-user resources, and webhooks. Widget metaFields, sensitiveMetaFields, and Capture blocks cannot change the linking values.

Security notes

• Mint tokens only from your backend. Your Ada API key must never reach a browser or mobile app.
• Never place an identity token in a URL, query parameter, or deep link.
• Do not log tokens, on the server or in the client.
• Treat a minted token like a password for the end user it names. Deliver it to the client over HTTPS only.

Next steps

Follow the identity tokens getting started guide to mint your first token and wire it into each SDK. It ends with a walkthrough that carries one conversation across two devices.

The Auth Tokens API reference documents the mint endpoint: request and response schemas, error codes, and rate limits.