Bring Your Own Identity (BYOI) - Thesys Documentation

Overview

BYOI lets you identify your users inside a Thesys-published agent. Instead of requiring end-users to create a Thesys account, you sign a lightweight JWT on your backend and pass it to the embedded agent. Thesys verifies the signature and scopes every conversation to the user ID you provide. What you get:

Per-user conversation history — no Thesys login required
Full control over user identification
Works with both the embed widget and direct iframe embedding
Automatic token refresh when JWTs expire mid-session

Quick Setup

Generate your Identity Secret

Open your agent in Agent Builder, click Share to open the publish side panel, and find the Bring Your Own Identity section.Click Generate Secret and copy the value. Store it securely on your backend — treat it like a password.

Never expose the Identity Secret in frontend code. It must only live on your server.

Sign a JWT on your backend

Create an HS256-signed JWT containing your user’s ID. The token must include:

Claim	Type	Required	Description
`externalUserId`	`string`	Yes	Your app’s unique user identifier
`exp`	`number`	Recommended	Expiration timestamp (Unix seconds)

const jwt = require('jsonwebtoken');

function generateIdentityToken(userId) {
  return jwt.sign(
    { externalUserId: userId },
    process.env.THESYS_IDENTITY_SECRET,
    { algorithm: 'HS256', expiresIn: '1h' }
  );
}

// Express endpoint
app.get('/api/thesys-token', (req, res) => {
  const token = generateIdentityToken(req.user.id);
  res.json({ token });
});

Set a reasonable expiration (e.g. 1 hour). If you configure automatic token refresh (see below), expired tokens are silently renewed without interrupting the user.

Pass the token to the agent

Choose the integration method that fits your setup:

Embed Widget (Recommended)
Direct iframe

Install the embed widget:

npm install agent-embed-widget

Pass identityToken for the initial token and getIdentityToken for automatic refresh on expiry:

import { embedWidget } from 'agent-embed-widget';

const { token } = await fetch('/api/thesys-token')
  .then(r => r.json());

embedWidget({
  url: 'https://console.thesys.dev/app/YOUR_SLUG',
  identityToken: token,
  getIdentityToken: async () => {
    // Called automatically when the token expires
    const res = await fetch('/api/thesys-token');
    const { token } = await res.json();
    return token;
  },
  hideLogin: true,
});

The widget handles the entire refresh cycle for you — when the JWT expires mid-conversation, it calls your getIdentityToken callback, gets a fresh token, and retries the failed request seamlessly.The widget supports three display modes: tray (default), full-screen, and chatbar.

Append IDENTITY_TOKEN and HIDE_LOGIN as URL query parameters:

<iframe
  id="thesys-agent"
  src="https://console.thesys.dev/app/YOUR_SLUG?IDENTITY_TOKEN=YOUR_JWT&HIDE_LOGIN=true"
  style="width: 100%; height: 600px; border: none;"
></iframe>

To set the token dynamically:

const token = await fetchTokenFromYourBackend();
const iframe = document.getElementById('thesys-agent');
iframe.src = `https://console.thesys.dev/app/YOUR_SLUG?IDENTITY_TOKEN=${token}&HIDE_LOGIN=true`;

Automatic token refresh for iframes requires a postMessage listener. See the Token Refresh section below for the full setup.

Automatic Token Refresh

When a JWT expires during an active conversation, the Thesys agent automatically requests a fresh token from the parent window using postMessage. If a new token is provided, the failed request is retried seamlessly — the user never sees an error.

How it works

If the parent doesn’t respond within 10 seconds (e.g. no listener configured), the agent falls back to showing an error modal asking the user to refresh the page.

If you’re using the embed widget, token refresh is handled automatically — just provide the getIdentityToken callback as shown in Step 3 above. No additional setup needed.

Direct iframe

For direct iframe embeds, add a message event listener on your parent page:

const iframe = document.getElementById('thesys-agent');

window.addEventListener('message', async (event) => {
  if (event.data?.type === 'THESYS_IDENTITY_TOKEN_REFRESH_NEEDED') {
    try {
      const res = await fetch('/api/thesys-token');
      const { token } = await res.json();

      iframe.contentWindow.postMessage({
        type: 'THESYS_IDENTITY_TOKEN_REFRESHED',
        identityToken: token,
      }, '*');
    } catch (error) {
      console.error('Failed to refresh identity token:', error);
    }
  }
});

PostMessage Protocol

Direction	Message Type	Payload
iframe → parent	`THESYS_IDENTITY_TOKEN_REFRESH_NEEDED`	(none)
parent → iframe	`THESYS_IDENTITY_TOKEN_REFRESHED`	`{ identityToken: string }`

How It Works Under the Hood

Thesys verifies the JWT signature using your Identity Secret (HS256)
The externalUserId claim is extracted and used to scope conversations
Each unique externalUserId gets its own isolated conversation history
If no identity token is provided, users are anonymous (session-based)
If a user is logged into Thesys and has an identity token, the identity token takes priority

Secret Rotation

If you need to rotate your Identity Secret:

Click Rotate Secret in the BYOI section of the publish panel
Copy the new secret to your backend environment
Redeploy your backend

Rotating the secret invalidates all previously signed tokens immediately. Users with old tokens will see an “Authentication Failed” error until they get a new token (via refresh or page reload).

Token Errors

Error	Cause	Resolution
Session Expired	JWT `exp` has passed	Handled automatically if token refresh is configured; otherwise the user must refresh the page
Authentication Failed	Signature doesn’t match (secret was rotated?)	Ensure your backend uses the current Identity Secret
Invalid Identity Token	Missing `externalUserId` claim	Add the required claim to your JWT payload
Identity Not Configured	No secret has been generated	Generate a secret in the publish panel

FAQ

Do I need to re-publish my agent after generating or rotating the secret?

No. The secret is synced to all published versions automatically.

Can I use the same secret across multiple agents?

No. Each agent has its own independent Identity Secret.

What JWT algorithm is supported?

Only HS256 (HMAC-SHA256). Other algorithms will be rejected.

Is there a token size limit?

No hard limit, but keep payloads small. Only externalUserId and exp are read by Thesys.

Can I add custom claims to the JWT?

Yes, but Thesys only reads externalUserId and exp. Extra claims are ignored.

What happens if I don't set up token refresh?

When the token expires mid-session, the agent shows an error modal. The user must refresh the page to continue. Configuring automatic refresh avoids this interruption entirely.

Does BYOI work with the chatbar widget type?

​Overview

​Quick Setup

​Automatic Token Refresh

​How it works

​Embed Widget

​Direct iframe

​PostMessage Protocol

​How It Works Under the Hood

​Secret Rotation

​Token Errors

​FAQ

Overview

Quick Setup

Automatic Token Refresh

How it works

Embed Widget

Direct iframe

PostMessage Protocol

How It Works Under the Hood

Secret Rotation

Token Errors

FAQ