Signed-in users: passing the user's token

By default the assistant knows nothing about who is chatting. In an application that is not enough: «show my unpaid invoices» needs your API to know which user is asking. The widget relays the user’s own token, and your tool sends it on to your API.

Three lines in your app

// after login, and on every token refresh:
Shukai.setUser(userToken);
// on logout:
Shukai.clearUser();
Shukai.clearHistory(); // on a shared browser — see below

userToken is any bearer-style string your endpoint accepts: not a cookie (we call your endpoint server-to-server, so cookies do not ride along), ideally short-lived and narrowly scoped, since it transits our servers. We treat it like a secret — never stored, never logged, never shown to the model — and still, a narrow token is good hygiene. Over 8,192 characters it is ignored, not cut.

setUser and clearUser are state, not queued: held in memory, read afresh on every message, safe to call before the widget mounts; the newest value wins.

One placeholder in your tool

In the custom tool’s headers, in the panel:

Authorization: Bearer {{user}}

{{user}} is substituted only at the moment of the HTTP call, like a secret. Your endpoint validates it exactly as it validates a request from your own front end: for you it is an ordinary authenticated request. When no token has been relayed — an anonymous visitor — a header that is nothing but Bearer {{user}} is dropped rather than sent empty, and a 401 or 403 from your endpoint tells the assistant the visitor appears to be signed out. Placeholders.

Why a token and not an id

A raw user id in the widget’s frame would be forgeable: the widget key is public, so anyone could send someone else’s id and read their data. A real token is a credential a visitor can present only for themselves. That is the whole design.

Where the token travels

The widget sends it as user_token on every message of the conversation and on every proactive tick. The runtime hands it to the tool call and nowhere else: not to the model, not to a log, not to the database. The tool’s response cache is keyed on the whole resolved request, headers included, so a response fetched with one user’s token is never reused for another.

Logout on a shared device

clearUser() forgets the token. It does not clear the device’s conversation history, which the widget keeps for up to seven days keyed by the widget, not by the user — the next person to log in on the same browser would otherwise see, and could continue, the previous visitor’s chats. Call clearHistory() too. The two are separate on purpose: a session that has merely expired forgets who the user is, but nobody else has sat down at the screen.

Only to signed-in users

The widget’s Install tab has a switch, «Only to signed-in users». With it on, the assistant is not drawn until your page calls Shukai.setUser(token), and it disappears again on Shukai.clearUser() — so your login, sign-up and password screens, which never call setUser, show nothing, and logging out takes it off the screen at once. No list of pages to keep.

A page reloads hidden, since the token lives in memory only; the moment setUser runs, the widget appears as on any page load and reopens a chat the visitor left open.

It decides where the assistant is shown, nothing more. The widget key is public, and nothing on our servers refuses a message without a user token. For pages rather than users, the same tab has «Every page» · «Every page except» · «Only these pages» — Configuration.

Our own panel as the example

The panel mints a 15-minute token for the signed-in owner, hands it to Shukai.setUser, and its co-pilot’s lookup tools call the panel’s own API with Bearer {{user}} — the same owner scoping as the panel itself. Its co-pilot has «Only to signed-in users» on, which is why the login screen shows no assistant. Your app does the same with its own tokens.