Identify signed-in users

By default every visitor is anonymous. When your app knows who the customer is, your backend can sign a short token that says so. The widget sends it to the desk, the desk checks the signature, and from then on:

agents see a verified contact (a ✓ next to the name) with the name, email and attributes your app sent;
the customer’s chats follow them across browsers and devices;
the AI’s actions can act on their account with {user.id}, {user.email}, {user.name} and {user.<attribute>}, which come from your token, never from the chat;
actions can call your API with the customer’s own key through {user.secrets.NAME}.

Identity only ever comes from a token the desk verifies. Nothing the page’s JavaScript says about the user is trusted on its own.

How it works

Create the identity secret

Go to Chat widget → Behaviour and press Create identity secret on the Identify signed-in customers card. Only owners and admins see this card.The secret starts with jis_. Use Show and Copy to get it, and store it on your server, for example as JUN_IDENTITY_SECRET. Never put it in front-end code.

Sign a token on your server

For the signed-in user, sign a JWT with HS256 and the identity secret. Keep it short-lived (an hour is plenty). See Claims and the examples.

Pass the token to the widget

Either put it on the snippet:

<script src="https://your-desk.example.com/widget.js" data-key="wk_…" data-user-token="eyJhbGciOi…" defer></script>

or call JunDesk.identify() once your app knows the user (for example after sign-in):

window.JunDesk?.identify(userToken);

Call logout when they sign out

window.JunDesk?.logout();

See Signing out.

The token travels two ways: over the loader’s live connection (so the Visitors list shows who’s on your site) and from the chat frame when it loads (so the conversation belongs to the right contact). With the round button (chat window, greeting card off), the chat frame loads on the first click, so that’s when the second check happens.

Claims

Claim	Required	What it does
`sub`	Yes	Your user’s id, as a string or number (up to 200 characters). This is the contact’s identity: same `sub`, same contact.
`exp`	Yes	Expiry, in seconds since the epoch. Expired tokens are rejected.
`nbf`	No	Not before, in seconds. A token isn’t accepted before it.
`email`	No	Shown to agents. Up to 320 characters.
`name`	No	Shown to agents and used by the AI to greet the customer. Up to 200 characters.
`attributes`	No	An object of facts about the customer, like `{ "plan": "pro", "seats": 12 }`.
`secrets`	No	The customer’s own keys for your API, like `{ "API_TOKEN": "…" }`. See User secrets.

The desk allows 60 seconds of clock skew on exp and nbf.

Attributes

Up to 50 keys. Each key must start with a letter or _, use only letters, digits and _, and be at most 40 characters. Other keys are skipped.
Values may be strings (cut to 500 characters), finite numbers or booleans. Anything else (objects, lists, null) is skipped.
Each verified token replaces the contact’s attributes: your app is the source of truth. name and email are updated when present and kept when left out.

Rejected tokens

A token is rejected, and the visitor stays anonymous, when:

Reason	Message in the browser console
Not three dot-separated parts, or unreadable JSON	`Malformed identity token.`
Signed with anything other than HS256	`Identity tokens must be signed with HS256.`
Wrong secret, or a rotated one	`Identity token signature doesn't match. Was it signed with this desk's identity secret?`
No `exp`, or it has passed	`Identity tokens need an exp (expiry) claim.` / `Identity token has expired.`
`nbf` in the future	`Identity token isn't valid yet.`
No `sub`	`Identity tokens need a sub (user id) claim.`
No identity secret on the desk	`Identity verification isn't set up for this desk (Chat widget → Behaviour → Identify signed-in customers).`

The chat frame logs these as [Jun] identify failed: …. Bad attributes (not an object) or bad secrets also reject the token.

Server examples

import jwt from "jsonwebtoken";

// For the signed-in user, e.g. in the handler that renders your app's page.
const userToken = jwt.sign(
  {
    sub: user.id,
    email: user.email,
    name: user.name,
    attributes: { plan: user.plan, seats: user.seats },
    // Optional: the user's own key for your API, for actions that act as them.
    secrets: { API_TOKEN: user.apiToken },
  },
  process.env.JUN_IDENTITY_SECRET,
  { algorithm: "HS256", expiresIn: "1h" },
);

import { createHmac } from "node:crypto";

const b64url = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");

export function junUserToken(user) {
  const header = b64url({ alg: "HS256", typ: "JWT" });
  const payload = b64url({
    sub: String(user.id),
    email: user.email,
    name: user.name,
    attributes: { plan: user.plan },
    exp: Math.floor(Date.now() / 1000) + 60 * 60,
  });
  const signature = createHmac("sha256", process.env.JUN_IDENTITY_SECRET)
    .update(`${header}.${payload}`)
    .digest("base64url");
  return `${header}.${payload}.${signature}`;
}

import os
import time

import jwt  # pip install PyJWT

def jun_user_token(user):
    return jwt.encode(
        {
            "sub": str(user.id),
            "email": user.email,
            "name": user.name,
            "attributes": {"plan": user.plan, "seats": user.seats},
            "exp": int(time.time()) + 3600,
        },
        os.environ["JUN_IDENTITY_SECRET"],
        algorithm="HS256",
    )

Then hand the token to the page, for example by rendering it into the snippet’s data-user-token attribute, or by returning it from an endpoint your front end calls before JunDesk.identify(token).

The token only needs to be valid when the widget sends it. Once verified, the browser stays linked to the contact, so a one-hour token doesn’t log the customer out of the chat after an hour. Only user secrets end with the token’s exp.

Merging rules

What happens when a browser identifies depends on who it was before:

The browser was…	Result
Anonymous, and this user is new to the desk	The anonymous contact becomes the user. Their chats stay as they are.
Anonymous, and this user already has a contact	The anonymous visitor’s conversations move to the user’s contact, and the anonymous contact is removed.
Already this user	The profile is refreshed (name, email, attributes).
Another identified user (a shared computer)	The browser gets a fresh link to this user. Nothing is merged.

Identified contacts never merge with each other, so one user can never inherit another user’s history. Merged conversations update in agents’ inboxes right away.

Signing out

Call JunDesk.logout() when the customer signs out of your app. It:

forgets the chat identity in this browser, so the next person starts fresh, with no access to the last person’s conversations;
drops the customer’s user secrets on the desk right away;
starts a new visitor session on the Visitors list.

Calling JunDesk.identify(null) also forgets the chat identity in the frame, but doesn’t start a new session. Use logout().

User secrets

Some APIs only accept the customer’s own key. Put it in the token’s secrets claim:

{ "sub": "u_123", "exp": 1767225600, "secrets": { "API_TOKEN": "cust_live_…" } }

Then use it in an action’s headers as {user.secrets.API_TOKEN} (Actions).

Names are UPPER_SNAKE_CASE: a capital letter, then capitals, digits and _, up to 64 characters.
Up to 10 secrets per token, each a non-empty string of up to 4,096 characters. A bad name or value rejects the whole token.
The desk keeps them only until the token’s exp, or until JunDesk.logout(). They’re kept apart from the contact: never stored with it, never shown to agents, never put in the AI’s prompt, and masked in action responses.
To keep them past exp, sign a fresh token and call JunDesk.identify() again.

Rotate or turn off the secret

On the Identify signed-in customers card:

Rotate secret creates a new one. Every token signed with the old secret stops working at once, so update your server first or right after.
Turn off removes the secret. Everyone becomes anonymous, and identify calls fail with “Identity verification isn’t set up for this desk”.

Actions

Use {user.id} and {user.secrets.NAME} in your API calls.

JavaScript API

identify, logout and the rest.

Get started

Deploy and run

Website widget

AI agent

Inbox and team

Agent as code

Reference

Identify signed-in users

How it works

Claims

Attributes

Rejected tokens

Server examples

Merging rules

Signing out

User secrets

Rotate or turn off the secret

Actions

JavaScript API

​How it works

​Claims

​Attributes

​Rejected tokens

​Server examples

​Merging rules

​Signing out

​User secrets

​Rotate or turn off the secret

Actions

JavaScript API

How it works

Claims

Attributes

Rejected tokens

Server examples

Merging rules

Signing out

User secrets

Rotate or turn off the secret