Skip to main content

Documentation Index

Fetch the complete documentation index at: https://katavenai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

KeyPrefixWhere it livesWhat it does
Public client keypk_live_<account>_<random>The customer’s web page (visible to browsers)Identifies the account + (optionally) pins to one agent
Secret keysk_live_<account>_<random>The customer’s backend only — never the browserUsed 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.