JWT & Identity

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

Why identity matters

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

JWT requirements

• 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, metadata.

aud and iss are accepted but not used by the AI. We recommend aud: "chatbyte" for consistency.

Identify a user

const bit = await createBit('your-agent-id');

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

Refresh tokens (recommended)

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

Metadata structure

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

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