> ## 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.

# Python SDK — widget keys

> Python SDK reference for `pk_live_` widget keys — the public identifiers embedded in your website's HTML.

`WidgetKeysClient` is reachable on every Kataven client as `client.widget_keys`. Each method maps to one HTTP endpoint on the [Hub API](/api-reference/introduction); links to the underlying spec entry are inline below.

`pk_live_` keys are the public identifiers you put in your website's HTML widget bootstrap. They're not credentials — domain allowlists keep them safe.

## Methods at a glance

| Method   | HTTP                                         | Summary                                                 |
| -------- | -------------------------------------------- | ------------------------------------------------------- |
| `list`   | `GET /api/v1/widget-keys`                    | List widget keys                                        |
| `create` | `POST /api/v1/widget-keys`                   | Create a widget key (returns plaintext pk\_live\_ ONCE) |
| `update` | `PATCH /api/v1/widget-keys/{widget_key_id}`  | Update or revoke a widget key                           |
| `delete` | `DELETE /api/v1/widget-keys/{widget_key_id}` | Delete or soft-disable a widget key                     |

## Reference

### `client.widget_keys.list(...)`

List widget keys

**HTTP** — `GET /api/v1/widget-keys` · [API reference →](/api-reference/introduction#tag/Widget%20Keys/operation/getApiV1WidgetKeys)

```python theme={null}
    def list(self) -> List[Dict[str, Any]]:
```

Returns metadata for every pk\_live\_ widget key in this account. The plaintext key value is never returned by this endpoint — only the last 8 characters and the row id. To recover a lost key, create a new one.

### `client.widget_keys.create(...)`

Create a widget key (returns plaintext pk\_live\_ ONCE)

**HTTP** — `POST /api/v1/widget-keys` · [API reference →](/api-reference/introduction#tag/Widget%20Keys/operation/postApiV1WidgetKeys)

```python theme={null}
    def create(
        self,
        name: str,
        domain_allowlist: Optional[List[str]] = None,
        agent_id: Optional[str] = None,
    ) -> Dict[str, Any]:
```

(pk\_live\_…) **once** — copy it into your embed snippet now.

* `domain_allowlist`: origins permitted to load the embed.
  Wildcards supported: `acme.com`, `*.acme.com`,
  `localhost:*`. **Empty allowlist = key blocked.**
* `agent_id`: optional pin. If set, the widget bootstrap
  forces this agent regardless of the embed's `data-agent`
  attribute.

Mints a new pk\_live\_ public identifier scoped to the caller's account. The plaintext value is returned in the response body and never again — paste it into the customer's HTML `<script data-client-key="...">` attribute.

### `client.widget_keys.update(...)`

Update or revoke a widget key

**HTTP** — `PATCH /api/v1/widget-keys/{id}` · [API reference →](/api-reference/introduction#tag/Widget%20Keys/operation/patchApiV1WidgetKeysById)

```python theme={null}
    def update(
        self,
        widget_key_id: str,
        name: Optional[str] = None,
        domain_allowlist: Optional[List[str]] = None,
        agent_id: Optional[str] = None,
        disabled: Optional[bool] = None,
    ) -> None:
```

widget sessions to fail their next bootstrap call.

Renames the key, replaces the domain allowlist, repins the agent, or revokes (disabled=true sets disabled\_at=now() — idempotent).

### `client.widget_keys.delete(...)`

Delete or soft-disable a widget key

**HTTP** — `DELETE /api/v1/widget-keys/{id}` · [API reference →](/api-reference/introduction#tag/Widget%20Keys/operation/deleteApiV1WidgetKeysById)

```python theme={null}
    def delete(self, widget_key_id: str) -> None:
```

using this key stop loading immediately.

Hard-deletes the row if the key was never used; otherwise sets disabled\_at=now() to preserve the audit trail.