airysdeveloper

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-jwt
value 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.