Embeddable Widget

Drop a voice/chat launcher into any website.

The Kataven widget is a voice/chat launcher you embed on any web page. End-users click it and talk (or chat) with one of your agents in their browser via WebRTC.

Two key types

Key	Prefix	Where it lives	What it does
Public client key	pk_live_<account>_<random>	The customer’s web page (visible to browsers)	Identifies the account + (optionally) pins to one agent
Secret key	sk_live_<account>_<random>	The customer’s backend only — never the browser	Used server-to-server to mint authenticated user tokens

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.

created = client.widget_keys.create(
    name="Acme website",
    domain_allowlist=["https://acme.com", "https://www.acme.com"],
    agent_id="<agent uuid>",  # optional pin
)
print(created["public_key"])  # pk_live_...
print(created["secret_key"])  # sk_live_... — save now

Widget settings

Two layers:

Account-level branding (/api/v1/widget-settings)

client.widget_settings.update(
    primary_color="#2563eb",
    accent_color="#7c3aed",
    logo_url="https://acme.com/logo.svg",
    launcher_position="br",         # br/bl/tr/tl
    launcher_label="Talk to us",
    privacy_notice="Calls may be recorded for quality.",
)

Per-agent policy (/api/v1/agents/{id}/widget-settings)

client.widget_settings.update_agent(
    agent_id="<agent uuid>",
    widget_enabled=True,
    auth_mode="both",   # guest | user | both
)

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 a domain_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.