Identity token reference (verifying your users)
This is the technical companion to the plain-language guide on identifying your users. It walks you through creating the secure sign-in token that tells airys exactly who a visitor is, so their past conversations and history are unlocked the moment they open the chat.
A few terms you will see below, in plain words first:
- JWT — a small, signed string your server creates to vouch for a logged-in user. (It stands for JSON Web Token.)
- HS256 — the signing method airys expects, where the same secret both creates and checks the signature.
- sub — the field inside the token that holds the unique ID for the user.
- claim — any single piece of information inside the token, like the email or name.
Step 1: Get your secret
In your dashboard, open the widget settings and generate (or rotate) your identity secret. You will also get a key ID to include alongside it. Store the secret safely on your own server. Never put it in your website code or anywhere a visitor could see it.
Step 2: Create a signed token on your server
When a user is logged in to your product, your server creates an HS256 token signed with that secret. Do this on the server side only.
Step 3: Put the right details inside
Include these in the token:
- sub — required. A unique ID for this user, up to 128 characters.
- email, name — optional, but helpful for your team.
- Custom attributes — optional extra details you want to attach.
- companyExternalId and companyName — optional. Use these to link the user to a company explicitly. airys never guesses a company from the email domain — it trusts only what you put here.
- exp — required. The token must expire within 24 hours.
Here is an example payload:
{
"sub": "user_8f31a2",
"email": "jordan@acme.com",
"name": "Jordan Lee",
"companyExternalId": "acme_inc",
"iat": 1748390400,
"exp": 1748476800
}
Step 4: Hand the token to the widget
Pass the finished token to the widget as the
data-user-jwtvalue on your install snippet, or supply it at the session step if you set up the widget that way.
Step 5: What airys does next
airys checks the signature with your secret. If it matches, airys trusts the details inside the token and nothing else — it never infers identity from the email domain. It then creates or updates the matching contact and starts a verified session, which unlocks that visitor's history.
A few good habits
- Keep the secret on your server only.
- Set a short expiry and create a fresh token per session.
- Send a stable
sub
so the same person always maps to the same contact.