JWT & Identity

JWT identity is optional but highly recommended. It lets the Widget associate conversations with real users and pass context to your agent.

Why identity mattersCopy Anchor Link

• Personalized responses for logged-in users.
• Consistent conversations tied to real accounts.
• Rich context (role, plan, org) for better answers.

JWT requirementsCopy Anchor Link

• Algorithm: HS256 only.
• Required claim: sub (unique user ID).
• Hard limit: exp - iat must be ≤ 10 minutes. Tokens over 10 minutes are rejected.
• Optional claims: aud, iss, email, name, fields.

Use fields for customer attributes such as a role or plan. Optional aud and iss claims are not used as customer context. The signing example uses aud: "chatbyte".

Create the token on your backend from the authenticated user's session. Derive their user ID and account information from your own records, rather than accepting these values directly from the browser.

Identify a userCopy Anchor Link

const widget = await createWidget('your-agent-id');

const token = await fetch('/api/widget-token').then((res) => res.json());
await widget.identify({ token: token.token });

Refresh tokens (recommended)Copy Anchor Link

widget.onRequestToken(async () => {
  const response = await fetch('/api/widget-token');
  const { token } = await response.json();
  return token;
});

Contact Fields structureCopy Anchor Link

const payload = {
  sub: 'user-123',
  email: 'user@acme.com',
  name: 'Avery Lee',
  fields: {
    plan: { value: 'pro', description: 'Billing tier' },
    role: { value: 'admin', description: 'Workspace role' },
  },
};

Legacy JWTs that still send metadata are accepted as an alias for fields, but new integrations should use fields.

Need the signing secret? See Identity (JWT) Signing Secret.

Fetch context from your serviceCopy Anchor Link

The identity token associates a Widget session with your user. Customer context complements it: the conversation.init callback lets your backend supply fresh information when a new conversation starts. Your backend remains responsible for authenticating the user and authorizing the information it returns; saved contact profiles are managed separately.