Public keys are the publishable credentials that let your widgets and forms
mount on external sites. A key looks like pk_live_… (or pk_test_… for a test
key) and is safe to ship in client-side code: it can only mount the surfaces you
scope it to, from the origins you allow.
Manage them on the Public keys page (/admin/public-keys, route
admin_public_keys_index, perm comerix.public_keys.view).
A public key is not a secret. Its protection is the allowed origins
list plus browser CORS — a script on an origin you didn’t allow can’t use it.
For server-to-server access you’d use a secret API key instead, which you
keep out of client code.
The keys list
The list opens on three summary tiles — active keys, total mounts
recorded, and distinct allowed origins (it flags any wildcard origin in
use) — above the keys themselves. Each row shows the key’s name and value, what
it mounts, its allowed origins, its recorded mounts, and its status
(Active, Paused, or Revoked). Use the All / Live / Test filter to
narrow by environment, or the search box to find a key by name, value, or origin.
Click a row to open the key’s detail page. If the workspace has no keys yet, the
page shows an empty state with Issue a public key.
Issue a key
Issue key (POST /admin/public-keys, perm comerix.public_keys.manage)
opens a drawer where you scope the new key — you can change everything later:
| Field | What it does |
|---|
| Key name | A label for your reference, e.g. where the key will live. |
| Environment | Live (real traffic) or Test (staging & local — clearly marked and ignored by analytics). The value gets the matching pk_live_ / pk_test_ prefix. |
| What this key can mount | All published forms & widgets, or only selected surfaces — pick specific forms and chat widgets from the list. |
| Allowed origins | One origin per line. Wildcards like https://*.acme.com are supported (a wildcard may only stand in for a subdomain, never the registrable domain). |
A single key
The detail page (/admin/public-keys/{id}) is where you read and adjust one key.
- Key — the full value with a copy button, plus when it was created, by whom,
and when it last mounted.
- Allowed origins — the origins the key mounts on; requests from anywhere
else are rejected before any widget loads. Wildcard origins are flagged. Edit
the list with Add origin (
POST /admin/public-keys/{id}/origins).
- Mounts — the forms and chat widgets the key may mount, or All published
forms & widgets. Adjust it with Edit scope
(
POST /admin/public-keys/{id}/scope).
- Usage — recorded mounts over the last 14 days as a sparkline, accrued from
real form renders and chat sessions that use the key.
- Recent activity — the key’s lifecycle, read from the audit log: created,
rotated, paused, resumed, origins/scope changes, and revoked.
Rotating a key
Rotate (POST /admin/public-keys/{id}/rotate) issues a new value
immediately while keeping the old one working for a grace window (48 hours by
default, or 24 hours / 7 days / none). Live embeds keep mounting on the old value
while you ship the new one; once traffic has moved over, revoke nothing further —
the old value simply stops working when the window ends.
Rotate, don’t revoke, when you just want to roll a key — rotation is
zero-downtime, revocation is immediate and final.
Pausing & revoking
- Pause / Resume (
POST /admin/public-keys/{id}/toggle) temporarily stops a
key mounting, then brings it back — handy while you investigate something.
- Revoke (
POST /admin/public-keys/{id}/revoke, in the Danger zone)
stops every widget and form using the key immediately, on every site. It
can’t be undone, so you type the key id to confirm. You’ll need to issue a new
key and update your embeds.
Where this key is used
The chat widget’s embed snippet lives on the Scripts page, which now
lets you pick which public key the snippet carries. For embedding a specific
form, see Forms → Embed & share.
Permissions
Grant these ACL leaves per role under Access → Roles:
| Resource | Grants |
|---|
comerix.public_keys.view | View the Public keys page and a key’s detail, value, origins, mounts, usage, and activity. |
comerix.public_keys.manage | Issue, rotate, pause/resume, revoke a key, and edit its allowed origins and mount scope. |
