Two key types
Both keys are minted as a pair via the admin endpoint and returned
exactly once. Save them immediately — the secret is bcrypt-hashed
on store and unrecoverable.
Widget settings
Two layers:Account-level branding (/api/v1/widget-settings)
Per-agent policy (/api/v1/agents/{id}/widget-settings)
auth_mode controls whether anonymous visitors (guest),
authenticated end-users (user), or both can talk to this agent.
End-user auth flows
The widget calls public, cross-origin endpoints to mint short-lived JWTs. There are two paths:Guest (anonymous)
Authenticated user
The customer’s backend mints an exchange token using its secret key, the browser swaps it for a real user JWT. The exchange endpoint re-validates the client key + Origin so a leaked exchange token can’t be replayed across origins.Refresh
POST /api/v1/widget/auth/refresh accepts an expired-grace-period
JWT and returns a fresh one. Skips Zitadel entirely — pure widget
token refresh.
Origin enforcement
Each public client key has adomain_allowlist. The widget auth
handler checks the request’s Origin (or Referer) header against
that list before minting any token. The cross-origin CORS plumbing is
permissive by design — the per-key allowlist is the actual security
boundary.
Widget SDK (browser side)
This page is about the management side. For the actual browser embed (<KatavenAgent /> component, KatavenClient for custom UIs),
see @kataven/client.