Anyone can call identify in a browser with any user ID, so without proof anyone could write in as one of your users. Customer identity gives Gleap that proof: after login, your backend signs a short identity token (a JWT) for the user and your app passes it to Gleap. Gleap then knows who the user is, and everything inside the token is signed: the user ID, the email, the company and attributes such as stripeCustomerId.
Five terms come up on this page and in the settings:
Identity key: the secret your backend signs tokens with. You create it in Gleap and keep it on your server.
Identity token: a short-lived JWT your backend signs for one logged-in user.
Signed session: what a user has once Gleap accepted their token. Gleap remembers it with a session grant (7 days by default), so your app doesn't send the token with every request. A user identified without a valid token is unsigned.
Protected field: a contact field that only a signed token may change.
Verified customer: a customer who proved who they are, with a signed session or an email code, before Kai or a tool reads or changes their data.
How it works
Settings → Security → Customer identity walks you through the setup under Sign your users in. The page has three steps: Create an identity key, Check a token from your backend and Turn on signed sessions. Signing the token and passing it to Gleap happen in your code, in between. In order:
Create an identity key and store its key ID and secret in your backend.
Sign a token on your backend with that key after your user logs in.
Pass the token to Gleap from your app with
setUserJwt, after login and on every app start.Check a token from your backend. Paste one on the page: Gleap shows whether it verifies and what it proves.
Turn on signed sessions.
From then on, Gleap stores the signed fields on the contact and returns a session grant. The SDK sends it with every request, so Gleap knows each request is signed without checking the token again.
Creating a key doesn't protect any fields and doesn't change how Gleap treats your users. Signed sessions start only when you click Turn on next to Turn on signed sessions and confirm with Turn on in the Turn on signed sessions? dialog.
Once signed sessions are on, the page shows their status, your Identity keys, Require a signature, Verified customers (a summary of the verification rules and your Protected fields) and More settings: Signed login lasts, Merge contacts by email and settings for older integrations, which the upgrade guide above explains.
Create an identity key
Open Settings → Security → Customer identity → Identity keys and click Create key.
Give it a label, for example "Production backend", and pick the platform it may sign for: all platforms (the default), web, iOS or Android.
Copy the key ID and the secret. Gleap shows the secret once.
Store both in your backend's configuration, for example as
GLEAP_IDENTITY_KEY_IDandGLEAP_IDENTITY_SECRET.
A project holds up to five keys. Only admins can see and manage identity keys.
Sign the token on your backend
The token is an HS256 JWT with the key ID in the kid header. Everything the contact should show goes into the token.
Claim | |
|---|---|
| Required. Your stable user ID as a string (at most 200 characters). |
| Set it. Expiry in seconds since the epoch, 5 to 60 minutes ahead. It only gates the sign-in; the session itself runs on the grant. A token without |
| Optional. Only an email your system has confirmed. Signing it means you vouch for it. |
| Optional. The user's name. |
| Optional. The user's phone number. |
| Optional. An object with |
anything else | A signed attribute: string, number or boolean, stored as custom data. Use |
Limits: at most 50 attributes, names of at most 64 characters (letters, digits and _), string values of at most 1,000 characters, and at most 4,096 characters for the whole token. Gleap allows 60 seconds of clock skew.
// npm install jsonwebtoken
const jwt = require("jsonwebtoken");
const token = jwt.sign(
{
userId: String(user.id),
email: user.email,
name: user.name,
company: { id: user.companyId, name: user.companyName },
stripeCustomerId: user.stripeCustomerId,
},
process.env.GLEAP_IDENTITY_SECRET,
{ algorithm: "HS256", keyid: process.env.GLEAP_IDENTITY_KEY_ID, expiresIn: "30m" }
);// composer require firebase/php-jwt
use Firebase\JWT\JWT;
$token = JWT::encode(
[
'userId' => (string) $user->id,
'email' => $user->email,
'name' => $user->name,
'company' => ['id' => $user->companyId, 'name' => $user->companyName],
'exp' => time() + 1800,
],
getenv('GLEAP_IDENTITY_SECRET'),
'HS256',
getenv('GLEAP_IDENTITY_KEY_ID')
);# pip install PyJWT
import os
from datetime import datetime, timedelta, timezone
import jwt
token = jwt.encode(
{
"userId": str(user.id),
"email": user.email,
"name": user.name,
"company": {"id": user.company_id, "name": user.company_name},
"exp": datetime.now(timezone.utc) + timedelta(minutes=30),
},
os.environ["GLEAP_IDENTITY_SECRET"],
algorithm="HS256",
headers={"kid": os.environ["GLEAP_IDENTITY_KEY_ID"]},
)# gem 'jwt'
require 'jwt'
token = JWT.encode(
{
userId: current_user.id.to_s,
email: current_user.email,
name: current_user.name,
company: { id: current_user.company_id, name: current_user.company_name },
exp: Time.now.to_i + 1800
},
ENV.fetch('GLEAP_IDENTITY_SECRET'),
'HS256',
{ kid: ENV.fetch('GLEAP_IDENTITY_KEY_ID') }
)// dotnet add package System.IdentityModel.Tokens.Jwt
var key = new SymmetricSecurityKey(
Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("GLEAP_IDENTITY_SECRET")))
{
KeyId = Environment.GetEnvironmentVariable("GLEAP_IDENTITY_KEY_ID"),
};
var header = new JwtHeader(new SigningCredentials(key, SecurityAlgorithms.HmacSha256));
var payload = new JwtPayload
{
{ "userId", user.Id.ToString() },
{ "email", user.Email },
{ "name", user.Name },
{ "exp", DateTimeOffset.UtcNow.AddMinutes(30).ToUnixTimeSeconds() },
};
var token = new JwtSecurityTokenHandler().WriteToken(new JwtSecurityToken(header, payload));// go get github.com/golang-jwt/jwt/v5
claims := jwt.MapClaims{
"userId": fmt.Sprint(user.ID),
"email": user.Email,
"name": user.Name,
"exp": time.Now().Add(30 * time.Minute).Unix(),
}
t := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
t.Header["kid"] = os.Getenv("GLEAP_IDENTITY_KEY_ID")
token, err := t.SignedString([]byte(os.Getenv("GLEAP_IDENTITY_SECRET")))Return the token to your app, for example in the login response or from an endpoint such as /api/gleap-token. Take the user ID and email from your authenticated server session, never from a value the browser sent.
Sign in from your app
Call setUserJwt after login and on every app start or page load of a logged-in user. The SDK keeps the token in memory only and stores the session grant with the session. setUserJwtProvider is optional: the SDK calls it for a fresh token when the grant is about to run out or a token was refused as expired. From SDK 19.5.0 (JavaScript 19.5.2) the provider also restores the signed session after an app restart or page reload when no grant is held; still call setUserJwt on every app start. Call clearIdentity on logout and before you sign in another user.
await Gleap.setUserJwt(token);
// Optional: fresh tokens for renewal
Gleap.setUserJwtProvider(async () => {
const response = await fetch("/api/gleap-token", { credentials: "include" });
return (await response.json()).token;
});
// On logout
Gleap.clearIdentity();Gleap.setUserJwt(token)
// Optional: fresh tokens for renewal (pass nil when it failed)
Gleap.setUserJwtProvider { completion in
MyBackend.fetchGleapToken { token in completion(token) }
}
// On logout
Gleap.clearIdentity()Gleap.getInstance().setUserJwt(token)
// Optional: fresh tokens for renewal (pass null when it failed)
Gleap.getInstance().setUserJwtProvider(GleapUserJwtProvider { callback ->
myBackend.fetchGleapToken { token -> callback.onToken(token) }
})
// On logout
Gleap.getInstance().clearIdentity()import Gleap from "react-native-gleapsdk";
await Gleap.setUserJwt(token);
Gleap.setUserJwtProvider(async () => await fetchGleapToken());
// On logout
Gleap.clearIdentity();await Gleap.setUserJwt(token: token);
Gleap.setUserJwtProvider(provider: () async => await myBackend.fetchGleapToken());
// On logout
Gleap.clearIdentity();import { Gleap } from "capacitor-gleap-plugin";
await Gleap.setUserJwt({ token });
Gleap.setUserJwtProvider(async () => await fetchGleapToken());
// On logout
Gleap.clearIdentity();You need JavaScript SDK 19.5.0 or newer, or 19.4.0 or newer of the iOS, Android, React Native, Flutter and Capacitor SDKs. The Cordova, .NET MAUI, Unity and Windows SDKs have no setUserJwt yet: pass the token as the signature argument of their identify call (see the user identity page of your SDK). That sign-in is verified, but those SDKs don't send the session grant yet, so their sessions count as unsigned afterwards.
updateContact still sends extra data such as the plan or the language, but it can't change protected fields. setAuthTokens({ backend: accessToken }) gives API tools a token to call your backend as this user; it works only for a signed-in user.
The session grant
The token proves the user once. Gleap then hands back a session grant, signed by Gleap itself, and the SDK sends it with every request from the SDK, the Messenger and the help center. A request with a valid grant is a signed request.
Lifetime. A grant lasts as long as Signed login lasts on the Customer identity page: 7 days by default, 1 to 30 days. The SDK option
sessionDurationcan only shorten it, to at least 5 minutes.The token's
expdoesn't end the session. A one-hour token doesn't log your user out after an hour.Renewal. Before the grant ends, the SDK asks your provider for a fresh token and signs in again, so a chat in progress keeps working. Without a provider, the next
setUserJwtcall renews it.When it expires. If the grant runs out and no fresh token arrives (your app doesn't call
setUserJwtand the provider returns nothing or isn't set), what happens depends on the platform:Web (JavaScript SDK 19.7.0 or newer): the signed session ends. The user continues as a visitor without conversation history. The next
setUserJwtsigns them in again, shows their full history, and merges what they did as a visitor on this device into their contact. If the Messenger is open when the grant runs out, the session ends when it's closed, at the latest one hour later.iOS and Android: the user stays identified but unsigned until the next
setUserJwtor provider token. They see their last 14 days of conversations, and protected fields keep their values.
Users you identify without a token were never signed, so nothing expires for them. They stay identified with 14 days of history.
Logout.
clearIdentitydrops the grant on this device. Revoking the key, or shortening Signed login lasts, ends grants everywhere.On the web the grant also lives in the cookie
gleap-grant-<projectId>, so your help center or feedback portal on the same domain is signed in too.
What a signed request unlocks
Signed fields
The token's claims land on the contact: email, name and phone in the matching fields, company on the company, everything else as custom data. A signed email counts as verified. In the contact view each signed field shows a check, the contact carries a Signed contact badge, and each conversation shows Verified or Unverified. When a later token no longer carries a custom attribute, that value is removed.
Protected fields
Choose which contact fields only signed updates may change: Settings → Inbox & tickets → Data attributes, tab Contact, switch Only signed updates. The user ID is always protected. Creating an identity key or turning on signed sessions doesn't protect any other field: you pick them here. Email, phone, company ID, company name and the billing and shop IDs are good candidates. The Customer identity page lists your protected fields under Verified customers.
A protected field changes only through a signed token, the server API, the dashboard, a CSV import, a workflow or Kai. A request from the app or the Messenger without a valid token leaves it unchanged and returns no error. An empty protected field may also be filled by the request that creates the contact. Leads (contacts with an email but no user ID) only have the user ID protected, so what a visitor types into the widget form is still saved.
Unsigned users and their history
An identified user whose requests carry no valid grant is unsigned: anyone could claim that user ID. Gleap then limits what the session can read. The widget shows only conversations with activity in the last 14 days; older ones stay in Gleap and your team still sees them. Unsigned answers never return protected values or signed data. Visitors and leads are never limited. A signed request, or requiring a signature on that platform, lifts the limit.
Require a signature
Require a signature on Settings → Security → Customer identity has one switch per platform (web, iOS, Android), with the signed logins of the last 7 days next to each. With it on, Gleap refuses an identify without a valid token on that platform with signature_required. Visitors and leads are never refused.
Turn a platform on once every app version you support there sends a token. The platform is what the SDK reports, so turn on every platform you ship to: an unsigned client could otherwise claim to be an app on a platform you left open. Gleap refuses to turn a platform on while no key could sign for it.
Rotate and test keys
Rotate a key. Create a new key, switch your backend to it, then Retire the old one. A retired key still verifies, so tokens already in your users' apps run out normally. When its Last used date stops moving, Revoke it. A revoked key never verifies again and ends the grants it signed. Revoke at once when a secret leaks.
Scope a key. A key for one platform verifies only sign-ins from that platform, so a leaked mobile key can't sign anyone in on the web.
Test a token. The token check on the Customer identity page (Check a token from your backend in the setup) checks a token without storing anything: which key matched, the claims, and what the token proves, or why it was refused. Signed logins, last 7 days counts signed sign-ins per platform.
Refused tokens
A bad token is always refused with an error: an app that sends a token wants to be signed, so a broken one never passes as unsigned. The code is in the error body's details.value.
Code | Status | Why | What the SDK does |
|---|---|---|---|
| 401 |
| Asks your provider once and retries. |
| 401 | Wrong signature, unknown or revoked key, wrong shape. | Keeps the session and logs a warning. |
| 401 | The platform requires a signature and none was valid. | Logs the code. |
| 400 | The token is for another user than the current session. | Starts over and signs in again. |
details.reason for token_invalid: key_unknown (no such key, or revoked), legacy_disabled (signed with the project secret while Accept user hash is off), no_key_matched (no key verifies the signature), user_mismatch (the token's user ID differs from the identify), key_platform (the key is scoped to another platform) or malformed (not a valid JWT, or no userId).
Call clearIdentity before you sign in another user and identity_mismatch never appears.
Tools that act for the customer
Verified customers on Settings → Security → Customer identity decides, per channel and audience, when a customer counts as verified for tools that read or change their data: billing, shop, Kai databases, and API and MCP tools.
Signed login: the conversation runs on a signed request. Only the Messenger supports it.
Email code: the customer confirms a 6-digit code sent to the email on file (3 tries, valid 10 minutes). On the Messenger through the Verify email card, on email and the chat apps by replying with the code.
By default, identified Messenger users count as verified with a signed login or the email code, and everyone else confirms the code. Each tool has a Verified customers only switch (always on for billing and shop tools). In tools, {{session.verifiedEmail}} holds the proven email, {{session.signedClaims.<name>}} a signed claim, and {{session.authTokens.<name>}} a token from setAuthTokens (signed customers only). In workflows, {{conversation.verification}} is signed_identity, verified_email or unverified, and the Customer verification condition branches on it.
Conversations your backend creates through the server-to-server API count as signed.
Help center, feedback portal and ticket links
They use the same sign-in as the widget, with no second login.
On your own domain, they read the grant cookie the JavaScript SDK set.
Elsewhere, hand the sign-in over:
Gleap.getIdentity()returns{ gleapId, gleapHash, grant }. Passgrantonly when it's set: without a signed session it isnull, and passing "null" makes the sign-in fail. See Sign visitors in to your help center.Single sign-on. The
ssoendpoints accept an identity token signed with your identity key, withaud: "sso"and anexpat most 10 minutes ahead. Each SSO token works once. Sign a separate token for SSO:identifyrefuses a token withaud: "sso".A session without a grant counts as logged out: it sees no restricted content and goes to your login URL.
Merge contacts
The same person can end up as several contacts: an email to your support address, a website chat before login, the app login. Contacts with their own user ID are never merged into each other.
Case | How |
|---|---|
A visitor chats, then logs in on the same device | Automatic. |
The user logs in with a signed email | Turn on Merge contacts by email under More settings on the Customer identity page. A contact without a user ID joins the user only when its email is proven: it emailed your support address, came from the server API, or confirmed the email with a code. Gleap never merges a guest who only typed the email, or an email contact whose inbound email failed SPF or DMARC. |
Your server creates the user |
|
Your server decides |
|
When a contact without a user ID writes with the email of an identified user, the inbox shows a warning that the message may not come from that user.
Shopify and WooCommerce
With the Gleap Shopify app or the WooCommerce plugin there's nothing to do: Gleap signs the storefront identities itself, so logged-in shop customers count as signed.

