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.

EXTRA_AUTH_MODE=host_token
EXTRA_AUTH_SECRET=${YOUR_JWT_SECRET}   # the key your app already signs with
EXTRA_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 EXTRA_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.EXTRA_AUTH_SECRET, {
      expiresIn: "1h", // required: tokens minted for us must expire
    }),
  });
});

EXTRA_AUTH_MODE=mint
EXTRA_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.

token-url is resolved like any other browser request: relative to the page. That is correct in production, where your app and its API share an origin. If your dev setup serves the frontend separately from your API, point it at the same base your own frontend uses.

When identity fails

Anything other than a clean token is reported — a wrong URL, an endpoint answering with the wrong shape, an unreachable host. The widget logs a warning and raises an event, so a broken integration cannot quietly look like a working anonymous chat:

document.querySelector("agent-chat").addEventListener("agent-chat:identity-error", (e) => {
  // { reason: "unauthorized" | "unreachable" | "malformed", status, url,
  //   anonymousFallbackEnabled }   <- whether falling back is allowed, not that it worked
  console.log(e.detail);
});

By default it then continues as an anonymous visitor. If a chat with no proven user is unacceptable in your product, opt out of that fallback entirely:

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

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 in and out

A normal page navigation needs nothing — the widget works out who the caller is on every load. A single-page app that signs a user in or out without reloading should say so, or the widget keeps the identity it already resolved:

const chat = document.querySelector("agent-chat");

chat.refreshIdentity();  // signed in, or switched user
chat.logout();           // signed out

Use refreshIdentity() on sign-in, not logout(). logout() discards the visitor pass, and that pass is what carries a visitor’s earlier conversations onto their account — calling it here throws them away instead of merging them.

Settings

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

Rotating EXTRA_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

When identity fails

Signing in keeps the conversation

Signing in and out

Settings

No login

Same domain

Other domain

​No login

​Same domain

​Other domain

​When identity fails

​Signing in keeps the conversation

​Signing in and out

​Settings

No login

Same domain

Other domain

When identity fails

Signing in keeps the conversation

Signing in and out

Settings