> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jun.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Identify signed-in users

> Prove who your signed-in customer is with a short-lived HS256 token, so agents see a verified contact and the AI can act on their own account.

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](/ai/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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](#claims) and the [examples](#server-examples).
  </Step>

  <Step title="Pass the token to the widget">
    Either put it on the snippet:

    ```html theme={null}
    <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):

    ```js theme={null}
    window.JunDesk?.identify(userToken);
    ```
  </Step>

  <Step title="Call logout when they sign out">
    ```js theme={null}
    window.JunDesk?.logout();
    ```

    See [Signing out](#signing-out).
  </Step>
</Steps>

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](#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

<CodeGroup>
  ```js Node.js (jsonwebtoken) theme={null}
  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" },
  );
  ```

  ```js Node.js (no dependencies) theme={null}
  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}`;
  }
  ```

  ```python Python (PyJWT) theme={null}
  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",
      )
  ```
</CodeGroup>

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)`.

<Tip>
  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](#user-secrets) end with the token's `exp`.
</Tip>

## 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](#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:

```json theme={null}
{ "sub": "u_123", "exp": 1767225600, "secrets": { "API_TOKEN": "cust_live_…" } }
```

Then use it in an action's headers as `{user.secrets.API_TOKEN}` ([Actions](/ai/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".

<CardGroup cols={2}>
  <Card title="Actions" icon="bolt" href="/ai/actions">
    Use `{user.id}` and `{user.secrets.NAME}` in your API calls.
  </Card>

  <Card title="JavaScript API" icon="brackets-curly" href="/widget/javascript-api">
    `identify`, `logout` and the rest.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.