Identity tiers
Chatbot uses three session identity levels.Anonymous
The visitor has an authenticated widget session but has not verified who they are. Use this tier only for information safe to expose to any visitor allowed to open the widget. A visitor typing an email address, order number, account ID, or name into chat does not upgrade the session’s identity tier.Verified email
The visitor proves control of an email address using RAUM’s one-time-code flow. This can unlock public resources whose policy requires email verification.Host signed
Your own authenticated website vouches for the visitor with a short-lived signed JWT. This is the strongest current Chatbot identity tier and is required for public WRITE actions.Email verification flow
When email verification is required, the widget can start a challenge using the visitor’s email address. Current safeguards include:- a 6-digit one-time code;
- challenge expiry after 10 minutes;
- no more than three recent challenges for the same session/email in the 15-minute anti-abuse window; and
- a bounded number of verification attempts.
Host-signed identity
For a visitor already signed in to your website, your server creates the identity token. Do not sign identity in browser JavaScript. The widget SDK/controller accepts the signed token through its identify operation. The current verifier requires an RS256 JWT with:- subject (
sub); - configured issuer (
iss); - configured audience (
aud); - issued-at (
iat); - expiration (
exp); - optional not-before (
nbf); and - only the allowlisted application claims you intend RAUM to receive.
Allowed host claims
Only configured primitive claims are copied into public Chatbot identity context. Supported allowlisted claim values are strings, numbers, or booleans. If an allowlistedemail claim is present and valid, RAUM can treat it as trusted email attached to the host-signed identity.
Do not expose an entire application session object as JWT claims. Put only the minimum customer identifiers/attributes required by public resource policy.
Public sources and identity
A public SOURCE policy can require:- Anonymous;
- Email verified; or
- Host verified/signed.
Public WRITE actions
Public WRITE actions require host-signed identity. The server rechecks the session identity before executing a confirmed action. Merely showing a confirmation UI is not enough to bypass identity policy. Public connections & actions →Identity and entity mappings
Host-signed claims can also feed deterministic Entity mappings. For example, a signed account/customer ID can be mapped as an external entity for conversation analytics without asking the AI classifier to infer ownership from prose. Entity mappings →Current administration note
The public runtime and widget-version data model support host-signed identity configuration. The current standard Widgets editor does not expose the issuer/audience/public-key fields alongside the normal Appearance/Language tabs. If host identity has not been provisioned for the widget, calling the identify flow with an arbitrary JWT does not enable it. The server fails closed when the verification configuration is unavailable or invalid.Security rules
- Generate/sign identity on your server.
- Keep the private signing key out of RAUM and out of browser code.
- Give RAUM only the public key and allowlisted claims needed for verification.
- Use short-lived tokens.
- Verify the exact issuer and audience configured for the widget.
- Do not treat browser telemetry, GeoIP, typed email, or conversation text as verified identity.