Anonymous sessions & sign-in promotion
A visitor should be able to start chatting before they sign in — and, when they do sign in, keep the conversation they already have. DioscHub treats anonymous sessions as first-class and promotes them in place on sign-in, so nothing is lost.
Bind anonymously to start
Section titled “Bind anonymously to start”To let a visitor chat without an account, bind the connection with no identity — send
identity: null (or omit it) on POST /auth/bind. That produces an anonymous binding. DioscHub
resolves the anonymous Role’s feature flags for the connection and hands
them to the widget when it signals ready.
The widget waits to be told its identity — including the anonymous one — before it starts a Session. Feature gating follows from this: the widget holds features closed until the bind delivers them, so an anonymous visitor sees exactly what the anonymous Role grants, never a signed-in default.
Anonymous-only embeds need no bind endpoint
Section titled “Anonymous-only embeds need no bind endpoint”If your page never signs anyone in (a public site assistant, a marketing page), you can leave
bindEndpoint out of the widget’s configuration. With no bind endpoint, the widget asks DioscHub for an
anonymous binding over its own connection, and DioscHub binds the connection itself. The visitor gets
the anonymous Role’s features, starter suggestions and commands (for example New Chat when the Role
allows several sessions), exactly as if your backend had bound with identity: null.
DioscHub does this only when all of these hold:
- the Assistant’s anonymous mode is enabled and the Assistant is active;
- the Assistant has an active
anonymousRole (DioscHub never falls back to another Role); - the deployment does not run in
host-requiredscope mode.
Otherwise nothing is bound, and the widget reports a failed bind in the browser console, as it did before.
A binding made this way is the same as an anonymous bind from your backend: no identity, no forwarded
auth, no REST token, the same origin check, rooms and anonymous
session limits (per device and per IP, plus the bot-protection challenge). The widget’s request carries
nothing DioscHub reads, so it can never claim an identity, a Role or credentials: asserting who a user
is still takes your backend’s auth:bind key. A connection your backend has already bound to a user is
never changed by it.
When you later add sign-in, add a bindEndpoint: from then on the widget calls your endpoint and
DioscHub stops binding the page itself.
Anonymous session limits
Section titled “Anonymous session limits”DioscHub limits how many new chats anonymous visitors can start on an Assistant, so that nobody can reset their per-session token budget by opening chat after chat:
| Limit | Default | Where to set it |
|---|---|---|
| New chats per browser | 5 per hour | anonymous Role dialog → Anonymous → Sessions per device; over the admin API anonymousConfig.sessionsPerDevice (0 turns it off) |
| New chats per network (client IP) | 60 per hour | Admin API only: anonymousConfig.sessionsPerIp on the anonymous Role (0 turns it off) |
Both count over the same rolling window: Window in the dialog, anonymousConfig.sessionsPerDeviceWindowMs
over the API (1 hour by default).
The browser is identified by an id the widget keeps in the browser’s storage. The network is the client IP,
so visitors behind one office or mobile-carrier address share its 60.
A limit applies only to starting a chat. A visitor who is over it keeps the chats they already have, and their next chat can start as soon as one of their earlier starts is older than the window.
When a chat can’t start
Section titled “When a chat can’t start”When DioscHub refuses to start a chat, the widget does not lose the visitor’s message:
- A line at the top of the chat says why, in plain words.
- The message goes back into the composer (with any files attached to it), so the visitor can send it again with Enter. Each send tries to start the chat again.
- The line goes away once a chat starts, or once the wait DioscHub gave has passed.
| Code | Why | What the visitor sees |
|---|---|---|
RATE_LIMITED (scope: 'ip') | The network’s new-chat limit is reached. | Too many new chats from this network. Try again in about 9 minutes. |
RATE_LIMITED (scope: 'device') | The browser’s new-chat limit is reached. | Too many new chats from this browser. Try again in about 9 minutes. |
CHALLENGE_FAILED | The bot-protection (friction) challenge failed. | We couldn’t verify this browser. Reload the page and try again. |
AUTH_REQUIRED | The Assistant does not allow anonymous chats, and the visitor is not signed in. | Sign in to chat with this assistant. |
ASSISTANT_INACTIVE, ANONYMOUS_NOT_CONFIGURED | The Assistant is not active on the current plan, or anonymous mode is on without an active anonymous Role. | This assistant isn’t available right now. |
NOT_CONNECTED | The widget is not connected to DioscHub. | Not connected. Check your connection and try again. |
Anything else (including START_TIMEOUT, no answer in 5 seconds) | Couldn’t start a chat right now. Please try again later. |
The wait is rounded up to the minute: in a minute under one minute, in about N minutes below an hour, in about an hour (or about N hours) beyond. With no wait from DioscHub the sentence ends Try again later. The visitor never sees the code or DioscHub’s own error text.
To react on your page (log it, or offer sign-in), subscribe to session:start_refused:
diosc('on', 'session:start_refused', ({ code, message, retryAfterMs, scope }) => { // message is the sentence the widget shows; retryAfterMs and scope come with RATE_LIMITED console.info('chat not started', code, retryAfterMs);});A diosc('invoke', …) whose chat is refused still resolves; the event is how your page learns of it. An
AUTH_REQUIRED refusal also fires auth:failed, as before.
Promote in place when the user signs in
Section titled “Promote in place when the user signs in”When the visitor signs in, re-bind the same connection with a real identity. DioscHub recognizes that the connection’s session is anonymous and promotes it rather than starting a new one:
- The conversation continues on the same session id — the message history is intact.
- The session’s owner becomes the signed-in user (
identity.userId). - The Assistant’s tool scope is re-resolved to the user’s Role, so the promoted session gets the signed-in user’s tools and features — not the anonymous set it started with.
- The widget receives a fresh session token and continues without reloading the conversation.
- Any files the visitor uploaded move into the signed-in user’s library (see Anonymous file upload).
To trigger this from the frontend after your app completes sign-in, call diosc('reauth'). The widget
re-runs the bind on its live connection; your bind endpoint now sees an authenticated user and passes a
real identity, and DioscHub promotes the session.
The sequence end to end
Section titled “The sequence end to end”- Page loads, widget connects, your bind endpoint returns an anonymous bind (
identity: null). (On a page with no bind endpoint, DioscHub makes this anonymous binding itself; see Anonymous-only embeds.) - The visitor chats; the Assistant runs with the anonymous Role’s tools and features.
- The visitor signs in through your app.
- Your app calls
diosc('reauth'); the widget re-binds with the signed-in user’s identity. - DioscHub promotes the session in place; the same conversation continues, now as the signed-in user with their Role’s tools.
Anonymous file upload
Section titled “Anonymous file upload”By default an anonymous visitor cannot upload files. For a helper or support assistant where visitors
attach evidence — a screenshot, a log — you can allow it per Assistant: turn on the Files feature
of the Assistant’s anonymous Role (role dialog → Features). It needs the Assistant’s
anonymousMode enabled, an active anonymous Role, and a license that includes file handling.
How access works
Section titled “How access works”An anonymous binding gets no REST token. Instead, when the Files switch is on, the session acknowledgement the widget receives on start (and on resume, restore or load) carries a short-lived files token scoped to that one session; with the switch off it carries none and the widget hides the upload control and the Files dialog. You never handle this token: the widget uses it only for its own file calls, and it never reaches the model, the logs or the session record.
- It is accepted only on the chat-file routes — upload, list, name check, get, download, rename, delete and the upload policy. File generation and every other API refuse it.
- It lives at most 24 hours from the session’s creation, and it is re-checked on every request against
the live session and the license. Promoting the session, or turning off the Assistant’s anonymous
mode, stops it on the next request (
401). The token is refused (401) on every chat-file route as soon as the session has ended: completed, expired, deleted or quarantined, or its row is gone. An expired (idle) session that its visitor comes back to is active again, and so is its token, within the 24 hours. - The Files switch takes effect for new sessions. A session keeps the setting it started with, so
turning Files off does not refuse a session that began with it on. To stop an existing anonymous
session’s file access at once, end, delete or quarantine that session; the token is refused (
401) immediately. - MCP file access and the
generate_fileandbundle_filestools stay refused for anonymous sessions, with or without the switch. The assistant’sfile_searchandread_filetools work on the visitor’s own current session files only, never another session’s and never a user library.
Files belong to the session
Section titled “Files belong to the session”An anonymous visitor’s files live with their session, not in a user library. They are listed, read and
changed only through that session: another session — even another session of the same visitor — gets
404 for them, as for a file that does not exist, and an upload naming a different session is refused
with 403.
Per-session caps, rate limit and friction
Section titled “Per-session caps, rate limit and friction”The Anonymous section of the anonymous Role’s dialog has a File uploads group with two caps:
| Field | Default | Range |
|---|---|---|
| Max files per session | 10 | 1 to 1000 |
| Max MB per session | 25 MB | 1 to 1024 MB |
Empty uses the default. Over the admin API they are anonymousConfig.filesMaxPerSession and
anonymousConfig.filesMaxBytesPerSession (bytes) on the Role; they travel with the Assistant in a
configuration transfer and are clamped to these ranges on import.
The caps act as the session’s storage quota: the effective quota is the smaller of the cap and any
storage quota the anonymous Role (or the system) sets.
An upload past it is refused with 413 QUOTA_EXCEEDED, and the
upload size limit still applies to each file.
Uploads also count against the deployment’s upload rate limit (by default 10 per minute and 100 per hour
per client), and a files token is only issued after the session start has passed the bot-protection
(friction) challenge and the anonymous session limits.
Expiry: 24 hours or the end of the session
Section titled “Expiry: 24 hours or the end of the session”An anonymous file is kept until 24 hours after the session was created or the end of the session, whichever comes first. If the Role’s or the system’s retention is shorter, that applies instead.
- A deleted session’s files are deleted at once.
- A session that ends otherwise — it expires, is completed or is quarantined — has its files deleted by the next hourly retention sweep.
- An upload into a session that has already ended is refused with
401, like every other call with its token. An upload already in flight when the session ends or is promoted is refused with403andcode: "ANON_SESSION_ENDED"; nothing is stored.
On promotion, files move to the user’s library
Section titled “On promotion, files move to the user’s library”When the visitor signs in and the session is promoted, the session’s files move into the signed-in user’s library on that Assistant:
- A name that clashes with a file the user already has gets the next free name (
report (2).pdf); nothing is overwritten. - The files count against the user’s storage quota from then on. If the move takes the user over their quota, every file still moves and nothing is evicted; the user’s next upload is refused until they free space.
- The 24-hour anonymous expiry no longer applies. Each file’s expiry is re-stamped from the user’s retention, counted from the move (none when retention is off).
- The anonymous files token stops working; the widget reaches the files with the user’s REST token.
Erasing the session erases its files
Section titled “Erasing the session erases its files”Erasing an anonymous session through data erasure also erases the files held by that session — their stored bytes, search index, permissions, derived files and records — and the verification pass reports any that remain. A signed-in user’s library files are not touched by a session erasure; erasing the user removes those.
Next: return to MCP server development to expose the tools a signed-in user can now reach, or configure Roles and Assistants in the admin portal.