Skip to main content
Public cross-origin endpoints called by the embeddable widget at runtime. Not for SDK use — these are bootstrap endpoints the browser calls directly during widget init. See Embeddable widget concept for the full handshake.

​
Endpoints at a glance

MethodPathSummary
POST/api/v1/widget/auth/exchangeExchange a server-minted visitor token for a widget session JWT
POST/api/v1/widget/auth/guestMint a guest visitor JWT for the embeddable widget
POST/api/v1/widget/auth/refreshRefresh a widget session JWT
POST/api/v1/widget/auth/user-tokenMint a logged-in visitor JWT (server-to-server)
GET/api/v1/widget/configGet the widget bootstrap config for a client_key

​
Reference

​
POST /api/v1/widget/auth/exchange

Exchange a server-minted visitor token for a widget session JWT The widget bootstrap calls this with the visitor token returned by the customer’s backend (via UserToken). Returns the live session JWT used for /connect. Request body (application/json) (empty object — no user-settable fields) Responses
CodeDescriptionBody
200OKobject
400Missing or expired tokenstring
Example 
curl https://api.kataven.ai/v1/widget/auth/exchange \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

​
POST /api/v1/widget/auth/guest

Mint a guest visitor JWT for the embeddable widget Cross-origin endpoint called from the widget bootstrap. The caller supplies the pk_live_ client key in the body; the server validates the request Origin against the per-key allowlist before minting a short-lived visitor JWT. No Authorization header required. Request body (application/json) (empty object — no user-settable fields) Responses
CodeDescriptionBody
200OKobject
400Missing client_keystring
403Origin not in allowlist for this client_keystring
Example 
curl https://api.kataven.ai/v1/widget/auth/guest \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

​
POST /api/v1/widget/auth/refresh

Refresh a widget session JWT Issued before the current widget JWT expires; returns a new short-lived JWT carrying the same identity claims. Request body (application/json) (empty object — no user-settable fields) Responses
CodeDescriptionBody
200OKobject
400Missing or expired refresh_tokenstring
Example 
curl https://api.kataven.ai/v1/widget/auth/refresh \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

​
POST /api/v1/widget/auth/user-token

Mint a logged-in visitor JWT (server-to-server) Server-to-server endpoint — the customer’s backend authenticates with an sk_live_ API key and mints a short-lived widget JWT bound to a specific user_id. The widget then uses that JWT to bootstrap. Request body (application/json) (empty object — no user-settable fields) Responses
CodeDescriptionBody
200OKobject
400Missing client_key or user_idstring
401Missing or invalid API keystring
Example 
curl https://api.kataven.ai/v1/widget/auth/user-token \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

​
GET /api/v1/widget/config

Get the widget bootstrap config for a client_key Returns the public-side config the widget needs to render — branding colors, copy, the agent’s display name. Cross-origin; client_key is supplied as a query parameter. Parameters
NameInTypeRequiredDescription
client_keyquerystringYespk_live_ public identifier
Responses
CodeDescriptionBody
200OKobject
400Missing client_keystring
403Origin not in allowliststring
Example 
curl https://api.kataven.ai/v1/widget/config \
  -H "Authorization: Bearer $KATAVEN_API_KEY"