Identity

Every conversation belongs to one person. Nobody else can list it, read it, or write to it, even knowing its id. Who that person is depends on your product:

No login

No accounts, or a public page. Nothing to do.

Same domain

Extra served from your site. Config only.

Other domain

Extra on its own hostname. One endpoint.

<script type="module" src="https://agents.acme.com/widget.js"></script>
<agent-chat title="Support"></agent-chat>

Each browser gets its own signed pass and its own conversations. Two people on the same page cannot see each other’s chats.

Same domain

Serve Extra from a path on the site your users already sign into — say acme.com/agents — and it reads the session they already have.

AGENT_AUTH_MODE=host_token
AGENT_AUTH_SECRET=${YOUR_JWT_SECRET}   # the key your app already signs with
AGENT_AUTH_COOKIE=session              # your session cookie's name

<script type="module" src="/agents/widget.js"></script>
<agent-chat title="Support"></agent-chat>

No code. The browser sends your cookie because it’s the same origin, and Extra verifies it with your own secret.

Works with any app that issues a session JWT — Open WebUI, Django, Rails, most Node stacks. If your user id isn’t in the sub claim, set AGENT_AUTH_CLAIM_USER_ID.

Other domain

Browsers won’t send your session cookie to a different hostname, so your backend vouches for the user instead.

app.get("/agent-chat/token", requireLogin, (req, res) => {
  res.json({
    token: jwt.sign({ sub: req.user.id }, process.env.AGENT_CHAT_SECRET, {
      expiresIn: "1h", // required: tokens minted for us must expire
    }),
  });
});

AGENT_AUTH_MODE=mint
AGENT_AUTH_SECRET=<32+ random characters>

<agent-chat title="Support" token-url="/agent-chat/token"></agent-chat>

Not logged in? Return 401 — the widget falls back to an anonymous pass.

Sign req.user.id from the session, never a value from the request. An endpoint that accepts ?user= lets anyone get a token as anyone.

Signing in keeps the conversation

Someone who chats before logging in doesn’t lose it. On their first authenticated request the widget hands their pass over and those conversations move onto their account. Automatic, and it only happens once.

Signing out

document.querySelector("agent-chat").logout();

Clears the stored identity and the open thread. Call it when your app signs a user out — and, in a single-page app, when it signs one in without a reload.

Settings

Variable	Default
`AGENT_AUTH_MODE`	`anonymous`	`anonymous`, `host_token`, or `mint`
`AGENT_AUTH_SECRET`	—	Signing key, 32+ characters. Required unless anonymous
`AGENT_AUTH_COOKIE`	—	Your session cookie’s name (`host_token` only)
`AGENT_AUTH_CLAIM_USER_ID`	`sub`	Claim holding the user id. Also `_EMAIL`, `_DISPLAY_NAME`, `_ROLES`
`AGENT_AUTH_MAX_TTL_SECONDS`	`3600`	Longest token accepted in `mint` mode
`AGENT_AUTH_ANONYMOUS_SECRET`	derived	Signs anonymous passes. Set it to survive a secret rotation

Rotating AGENT_AUTH_SECRET is safe: widgets fetch a fresh token on their next request.

Get Started

Core Concepts

Features

Widget

Reference

No login

Same domain

Other domain

Same domain

Other domain

Signing in keeps the conversation

Signing out

Settings

No login

Same domain

Other domain

​No login

​Same domain

​Other domain

​Signing in keeps the conversation

​Signing out

​Settings

No login

Same domain

Other domain

Signing in keeps the conversation

Signing out

Settings