Widget keys API

Widget keys authorise the embedded widget to talk to one chatbot from the domains you allow.

These endpoints require session authentication. The keys they produce are used by the widget with key authentication.

Generate a key

POST /chatbots/:chatbotId/widget-keys

{
  "label": "Production — example.com",
  "allowedDomains": ["example.com", "www.example.com"]
}

Field	Notes
`label`	For your own reference in the dashboard
`allowedDomains`	Origins allowed to use this key

Returns:

{
  "success": true,
  "data": {
    "key": "the_full_secret_key_shown_once",
    "widgetKey": {
      "id": "...",
      "label": "Production — example.com",
      "keyPrefix": "sk_abc1",
      "allowedDomains": ["example.com", "www.example.com"],
      "isActive": true,
      "createdAt": "2026-07-21T10:30:00.000Z"
    }
  }
}

data.key is returned exactly once

The full key appears in this response and never again — it is stored hashed. If your automation does not capture it here, it is gone and you must generate a replacement.

keyPrefix is a short non-secret fragment kept so you can recognise which key is which in a list. It cannot be used to authenticate.

Allowed domain matching

Entry	Matches
`example.com`	Exactly `example.com` — not `www.example.com`
`*.example.com`	`example.com` and every subdomain
`*`	Any origin

An empty allowedDomains array rejects every request. It is a closed key, not an open one. Always supply at least one entry.

Avoid * on production keys — it permits every site on the internet to use your chatbot.

List keys

GET /chatbots/:chatbotId/widget-keys

Returns data.keys. Each entry includes the label, key prefix, allowed domains, active state, creation time, and usage figures — how many times it has been used and when it was last seen.

The secret is never included. There is no endpoint that returns it.

Usage figures are how you detect a key being used from somewhere you did not expect.

Revoke a key

DELETE /chatbots/:chatbotId/widget-keys/:keyId

{
  "success": true,
  "data": { "message": "Key revoked successfully" }
}

Revocation takes effect immediately. Any widget still using the key receives 401 Invalid or revoked API key and stops working.

Rotating a key without downtime

Generate a new key with the same allowed domains
Deploy the new key to your site
Confirm the widget works
Then revoke the old key

Revoking first produces a dead widget for however long the deployment takes.

Verify step 3 properly before step 4 — check the usage counter on the new key has started climbing, not just that the page looks right.

Sensible key hygiene

One key per site, so revoking one never affects another
One key per environment, with staging keys restricted to staging hostnames
Revoke on exposure — a key pasted into a public repository, a support ticket, or a screenshot should be replaced, not tolerated
Never use * outside local testing

→ Widget keys, explained for non-developers

Generate a key​

Allowed domain matching​

List keys​

Revoke a key​

Rotating a key without downtime​

Sensible key hygiene​