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.
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 |
|
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
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.
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.
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.
Sign tokens on your backend and ship an app version that calls
setUserJwt(token)after login and on every app start, with asetUserJwtProviderfor renewal. See Sign the token on your backend.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.
Require a signature on each platform once every app version you support there sends a token.
Old calls and their replacements
Before | Now |
|---|---|
|
|
iOS |
|
Android |
|
React Native |
|
Flutter |
|
Capacitor |
|
HMAC-SHA256 of the user ID with the project secret | HS256 JWT signed with an identity key, |
Enforce identity verification | Require a signature per platform |
Project secret as | A REST API key (Settings → Security → REST API keys) |
Help center and portal SSO with a derived signing key | An identity token with |
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
setUserJwtyet. 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.