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

# Node SDK — widget keys

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

`WidgetKeysResource` is reachable on every Kataven Node client as `client.widgetKeys`. 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/{id}`  | Update or revoke a widget key                           |
| `delete` | `DELETE /api/v1/widget-keys/{id}` | Delete or soft-disable a widget key                     |

## Reference

### `client.widgetKeys.list(...)`

List widget keys

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

```typescript theme={null}
list()
```

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.widgetKeys.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)

```typescript theme={null}
create(input: { name: string; domain_allowlist?: string[]; agent_id?: string | null })
```

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.widgetKeys.update(...)`

Update or revoke a widget key

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

```typescript theme={null}
update(id: string, patch: { name?: string; domain_allowlist?: string[]; agent_id?: string | null; disabled?: boolean })
```

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

### `client.widgetKeys.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)

```typescript theme={null}
delete(id: string)
```

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