Authentication
The visitor trust ladder - anonymous, prefilled, and verified-identified - and which proof to use
By default the widget works anonymously. To attribute conversations to a known user, or to gate sensitive data behind a real identity, identify the visitor with a cryptographic proof produced on your server.
The Trust Ladder
| Level | Established by | Server trust | Can gate sensitive data? |
|---|---|---|---|
| Anonymous | A random visitor id in localStorage | none | No |
| Prefill (unverified) | Host passes name / email / phone | none | No |
| Verified-identified | A cryptographic proof made outside the browser (JWT, HMAC, Google, or passkey) | verified user id | Yes |
The browser only carries a proof. It never produces one. Anything sensitive is gated on the verified identity and scoped to the verified user id, never to a raw email.
The Proofs
| Proof | Trust anchor | Expires? | Needs a host backend? | Use when |
|---|---|---|---|---|
| Signed JWT (HS256) | Your integration's shared secret | Yes (exp) | Yes | Recommended for any site with a backend and logged-in users. |
HMAC (user_hash) | Shared secret | Never | Yes | Legacy / Intercom-style migration. Prefer JWT. |
| Google (FedCM) | Google's keys | Yes | No | Public sites with no backend - let visitors sign in with Google. |
| Passkey (WebAuthn) | The visitor's device | Per use | No | In-page embeds wanting passwordless sign-in. |
You can attach profile data (name, email, phone, custom attributes) to any proof.
Which Proof to Use
- You have a backend and your own login. Use a signed JWT. It is short-lived, carries a trusted profile, and self-revokes.
- You are migrating from Intercom's
user_hash. The HMAC proof is the drop-in equivalent. Plan to move to JWT. - You have no backend. Enable Google sign-in or passkeys. The widget handles sign-in in the panel.
The Shared Secret
JWT and HMAC proofs are both signed with your integration's shared secret, the value revealed once at widget creation. It is encrypted at rest, never sent to the browser, and never appears in the widget's public config.
Sign server-side only. If the secret ever reaches client JavaScript, treat it as leaked and rotate it.
Anonymous Visitors
Even with Require sign-in enabled, an anonymous visitor gets a session and can read content, react, and browse. Require sign-in gates only the messenger. The widget refuses an unverified visitor's outbound message and replaces the composer with a sign-in panel. See Sessions.