Python SDK — widget keys

WidgetKeysClient is reachable on every Kataven client as client.widget_keys. Each method maps to one HTTP endpoint on the Hub API; 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 →

    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 →

    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 →

    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 →

    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.

Get started

Resource reference

Python SDK — widget keys

Methods at a glance

Reference

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

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

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

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

​Methods at a glance

​Reference

​client.widget_keys.list(...)

​client.widget_keys.create(...)

​client.widget_keys.update(...)

​client.widget_keys.delete(...)

Methods at a glance

Reference

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

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

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

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