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.

Two pieces:
  1. Server-side: mint a public client key (pk_live_…) for your website’s domain.
  2. Browser-side: load the widget JS and hand it the public key.

​
1. Mint a client key

created = client.widget_keys.create(
    name="acme.com production",
    domain_allowlist=["https://acme.com", "https://www.acme.com"],
    agent_id="<agent uuid>",   # optional; pins this key to one agent
)
print("PUBLIC:", created["public_key"])  # save in your frontend env
print("SECRET:", created["secret_key"])  # save in your backend env (only if using authenticated end-users)
Both keys are returned once. Save them now.

​
2. Drop the widget on your page

<script src="https://widget.kataven.ai/v1.js"></script>
<script>
  Kataven.init({
    publicKey: "pk_live_acme_xxxxxxxxxxxxxxxxxxxxxxxxxx",
    // agentId: "..."   // omit if your client key is pinned
  });
</script>
The widget injects a launcher button at the position you configured in widget_settings. End-users click it and start talking.

​
3. (Optional) Authenticated end-users

If your agent’s auth_mode is user or both, you can identify the visitor: 
// From the customer's backend, mint an exchange token:
const response = await fetch("https://api.kataven.ai/hub-api/api/v1/widget/auth/user-token", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KATAVEN_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_user_id: user.id,
    display_name: user.name,
    email: user.email,
  }),
});
const { user_token } = await response.json();
// Hand `user_token` to your frontend; it has 5-minute TTL.

// Browser-side, hand the user_token to the widget:
Kataven.init({
  publicKey: "pk_live_...",
  userToken: user_token,   // browser swaps this for a real user JWT
});
The widget’s Kataven.init takes care of the exchange call.

​
Troubleshooting

ErrorCause
origin_not_allowedPage’s Origin header isn’t in the widget key’s domain_allowlist. Add it via widget_keys.update(...).
widget_disabled_for_agentThe agent’s widget_enabled = false. Toggle in the dashboard or via widget_settings.update_agent.
guest_not_allowedThe agent only allows authenticated users. Use the user-token flow above.
client_key_disabledThe key was disabled. Re-enable or rotate.