Endpoints at a glance
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
Example
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
Example
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
Example
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
Example
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
Responses
Example