--- title: "Upgrade to identity tokens" description: "What changed from the user hash to identity tokens, why, and how to move an existing integration over step by step." url: https://docs.gleap.ai/en/articles/16752008-upgrade-to-identity-tokens collection: "Guides" updated: 2026-11-07 language: en --- # Upgrade to identity tokens What changed from the user hash to identity tokens, why, and how to move an existing integration over step by step. Gleap now signs your users in with **identity tokens**: a short JWT your backend signs with an identity key. It replaces the user hash, the HMAC of the user ID that your backend used to compute with the project secret. This guide explains what changed, why, and how to move an existing integration over. For the full reference, see [Customer identity](https://docs.gleap.ai/en/articles/709-enforce-identity-verification.md). ## Why we changed it The user hash proved one thing: the user ID. Everything else your app sent next to it (email, company, plan, billing IDs) could be changed by anyone who called `identify` in the browser. Identity tokens close that gap.

	User hash	Identity token
Proves	The user ID only	User ID, email, company and any attribute you sign
Secret	The project secret, which also authenticated the server API	Identity keys used only for this, with rotation, retirement and per-platform scope
Expiry	Never	`exp` on every token, plus a session grant that ends after Signed login lasts
Field protection	None	Only signed updates per field
Enforcement	One switch for all platforms	Require a signature per platform
Kai and tools	No notion of a verified customer	Verified customers per conversation, with an email code as the fallback
Help center and portal	Separate sign-in	The same sign-in as the widget

## What happens to your project - **Existing projects** keep working exactly as before until you switch them. The **Security** page shows a **Classic** card with **Switch to signed identities**. - **Switching** a project to signed identities (the switch, or creating the first identity key) turns on session grants, protected fields and the 14-day history limit for unsigned users. User hashes stay accepted while **Accept legacy user hash** is on, so nothing breaks the day you switch. - **New projects** start with signed identities and accept identity tokens only. ## Upgrade step by step 1. **Update the Gleap SDKs** in your apps: JavaScript 19.5.0 or newer, and 19.4.0 or newer for iOS, Android, React Native, Flutter and Capacitor. Keep sending the user hash for now. 2. **Switch the project** under **Settings → Security → Customer identity**. Identified users without a valid signature, including older app versions, now see only the last 14 days of conversations. 3. **Create an identity key** and store its key ID and secret in your backend. The first key protects email, phone, company ID, company name and the billing and shop IDs. In **Settings → Inbox & tickets → Data attributes**, turn **Only signed updates** off for any field your apps still send without a token. 4. **Sign tokens on your backend** and ship an app version that calls `setUserJwt(token)` after login and on every app start, with a `setUserJwtProvider` for renewal. See [Sign the token on your backend](https://docs.gleap.ai/en/articles/709-enforce-identity-verification.md). 5. **Watch Signed logins** on the Security page. When no app sends the user hash any more (the page suggests it after 7 days without one), switch **Accept legacy user hash** off. 6. **Require a signature** on each platform once every app version you support there sends a token. ## Old calls and their replacements

Before	Now
`Gleap.identify(id, data, userHash)`	`await Gleap.setUserJwt(token)`; put the data into the token
iOS `identifyContact(id, andData:, andUserHash:)`	`Gleap.setUserJwt(token)`
Android `sessionProperties.setHash(hash)`	`Gleap.getInstance().setUserJwt(token)`
React Native `identifyWithUserHash(id, data, hash)`	`await Gleap.setUserJwt(token)`
Flutter `identify(..., userHash: hash)`	`await Gleap.setUserJwt(token: token)`
Capacitor `identify({ userId, userHash })`	`await Gleap.setUserJwt({ token })`
HMAC-SHA256 of the user ID with the project secret	HS256 JWT signed with an identity key, `kid` in the header
Enforce identity verification	Require a signature per platform
Project secret as `Api-Token` for the server API	A REST API key (Settings → Security → REST API keys)
Help center and portal SSO with a derived signing key	An identity token with `aud: "sso"`

Data you used to send unsigned next to the hash (plan, company, custom data) can stay in `updateContact`, as long as the field isn't protected. Values you want to rely on belong in the token. ## Good to know - **Older app versions** keep working while **Accept legacy user hash** is on, but their sessions count as unsigned: a 14-day history, Kai treats them as unverified, and protected fields stay as they are. An older SDK can also send a token in place of the hash; that sign-in is verified, but the session stays unsigned because those versions don't send the grant. - **Cordova, .NET MAUI, Unity and Windows** have no `setUserJwt` yet. Pass the token where they took the hash. - **WordPress plugin logins** are signed with the user hash until the plugin's next release. Keep **Accept legacy user hash** on until then. - **Classic projects** that never switch keep the old behaviour, including the user hash and **Enforce identity verification**. ## Related - [Customer identity](https://docs.gleap.ai/en/articles/709-customer-identity.md) - [Authenticated conversation files](https://docs.gleap.ai/en/articles/710-authenticated-conversation-files.md) - [Data regions](https://docs.gleap.ai/en/articles/711-data-regions.md) - [Connect the Gleap MCP](https://docs.gleap.ai/en/articles/712-connect-the-gleap-mcp.md) - [Plans and AI pricing](https://docs.gleap.ai/en/articles/713-plans-and-ai-pricing.md)