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.

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.