> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kataven Hub API — widget visitor auth

> REST API reference for the public widget bootstrap auth endpoints. Cross-origin; called from customer pages, not your backend.

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](/concepts/widget) for the full handshake.

## Endpoints at a glance

| Method | Path                                                                    | Summary                                                         |
| ------ | ----------------------------------------------------------------------- | --------------------------------------------------------------- |
| `POST` | [`/api/v1/widget/auth/exchange`](#post-api-v1-widget-auth-exchange)     | Exchange a server-minted visitor token for a widget session JWT |
| `POST` | [`/api/v1/widget/auth/guest`](#post-api-v1-widget-auth-guest)           | Mint a guest visitor JWT for the embeddable widget              |
| `POST` | [`/api/v1/widget/auth/refresh`](#post-api-v1-widget-auth-refresh)       | Refresh a widget session JWT                                    |
| `POST` | [`/api/v1/widget/auth/user-token`](#post-api-v1-widget-auth-user-token) | Mint a logged-in visitor JWT (server-to-server)                 |
| `GET`  | [`/api/v1/widget/config`](#get-api-v1-widget-config)                    | Get 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**

| Code  | Description              | Body     |
| ----- | ------------------------ | -------- |
| `200` | OK                       | `object` |
| `400` | Missing or expired token | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/widget/auth/exchange \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{...}'
  ```
</CodeGroup>

### `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**

| Code  | Description                                  | Body     |
| ----- | -------------------------------------------- | -------- |
| `200` | OK                                           | `object` |
| `400` | Missing client\_key                          | `string` |
| `403` | Origin not in allowlist for this client\_key | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/widget/auth/guest \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{...}'
  ```
</CodeGroup>

### `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**

| Code  | Description                       | Body     |
| ----- | --------------------------------- | -------- |
| `200` | OK                                | `object` |
| `400` | Missing or expired refresh\_token | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/widget/auth/refresh \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{...}'
  ```
</CodeGroup>

### `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**

| Code  | Description                     | Body     |
| ----- | ------------------------------- | -------- |
| `200` | OK                              | `object` |
| `400` | Missing client\_key or user\_id | `string` |
| `401` | Missing or invalid API key      | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/widget/auth/user-token \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{...}'
  ```
</CodeGroup>

### `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**

| Name         | In    | Type     | Required | Description                  |
| ------------ | ----- | -------- | -------- | ---------------------------- |
| `client_key` | query | `string` | Yes      | pk\_live\_ public identifier |

**Responses**

| Code  | Description             | Body     |
| ----- | ----------------------- | -------- |
| `200` | OK                      | `object` |
| `400` | Missing client\_key     | `string` |
| `403` | Origin not in allowlist | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/widget/config \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>