Rotate or revoke a key

What it is

There is no "regenerate" button on an existing key, because the plaintext secret only ever exists at the moment of creation. Rotation is therefore three deliberate steps:

1. Create a replacement key.
2. Deploy it to the system that needs it and confirm it works.
3. Revoke the old key.

Revoking is immediate and permanent. Any integration still presenting that key starts getting 401 on the next request — there is no grace period and no undo.

Revoking a key never affects your dashboard session. The two are entirely separate credentials.

When you would use it

Revoke immediately, before anything else, when a key has leaked: committed to a repository, pasted into a ticket or chat, included in a screenshot, or sitting on a laptop that was lost. Investigate afterwards. A key you are unsure about is a key to revoke.

Rotate on a schedule when someone with access has left the team, when an expiry is approaching, or when you are tightening scopes on an integration that grew.

Just revoke when the Last used column shows a key nothing has touched in months.

Where to find it

Open Dashboard → Settings → Developer. Each row in the key table has a revoke action. The tab is owner-only.

Steps — planned rotation

1. Open Dashboard → Settings → Developer as the account owner.
2. Create a new key. Give it a name that distinguishes it from the old one — appending the date works well: wordpress-production-2026-08.
3. Grant the same scopes, or narrower ones if the integration turned out to need less. Scopes cannot be changed later. See Choose token scopes.
4. Copy the secret and store it in your secret manager.
5. Deploy the new secret to the system that holds it, and restart or reconnect whatever caches it.
6. Make one real call and confirm it succeeds.
7. Watch the Last used column. The new key should start updating; the old one should go quiet.
8. Only then revoke the old row and confirm the danger prompt.
9. Migrate one system at a time. Revoking every key at once, mid-migration, is how a routine rotation becomes an outage.

Steps — a leaked key

1. Open Dashboard → Settings → Developer and revoke the exposed key now. Accept the brief outage.
2. Create a replacement with the narrowest scopes that still work.
3. Deploy it and confirm the integration recovers.
4. Remove the secret from wherever it leaked — rewrite the repository history, delete the message, edit the ticket. A revoked key is harmless, but a leaked-secret habit is not.
5. If the key was pasted into a support conversation, tell support that you have rotated it, and do not resend the secret.
6. Review what that key could reach. A widget:manage key exposes far less than a chatbots:write one, and that difference decides how much of step 7 you need.
7. Check what changed in the account while the key was live — chatbots, knowledge sources, and allowed domains are the surfaces a stolen key would touch.

What you will see

Each key row shows Name, Scopes, Created, Last used, and Expires, with the revoke action at the end. Revoking asks for confirmation and warns that any integration still using the key will stop working immediately.

After confirming, the row disappears from the table. There is no archive view — the audit trail you keep is the naming convention and your own change log.

Expiry versus revocation

Both end a key, but they are not interchangeable:

• Expiry is set when the key is created and cannot be extended afterwards. When it passes, calls start failing with 401. There is no warning email, so put the date in a calendar.
• Revocation is the manual, immediate version. It is the correct response to a leak and the correct end to a rotation.

If you want a key gone before its expiry, revoke it. That is what "expire early" means here.

Verifying it actually worked

A revocation you cannot confirm is not a completed task:

curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/chatbots \
  -H "Authorization: Bearer $OLD_TOKEN" \
  -H "Accept: application/json"

A revoked key returns 401. Use your own API host — see API host — no /api prefix, because a 404 here means you tested the wrong URL and proved nothing.

Limits and plan notes

Revocation is per key. Revoking one leaves every other key, and your browser session, untouched.

An old secret can never be displayed again, so a key you did not copy is a key to revoke and replace.

Only the account owner can create or revoke keys, and no self-service key can do it on your behalf — key management is deliberately outside the scopes a key may hold.

Site plugins hold their own copy of the secret. Revoking the key does not remove the site's registration or its entry on the allowed-domain list; reconnect the plugin with the new key, and clean up the domain list separately if the site is genuinely going away. See Allowed domains for the widget.

Common problems

The plugin still fails after I pasted the new key.

Most plugins cache credentials. Save the settings, then reconnect or restart so the new secret is actually picked up.

I revoked the wrong key.

It cannot be restored. Create a replacement with the same scopes and redeploy — the interruption lasts as long as your deploy does.

Everything broke at once after a rotation.

Several systems were sharing one key. Give each system its own from now on; that is the whole reason the table has a Name column.

A key expired and I did not notice.

Expired keys fail silently from the outside — the integration just stops. Create a replacement and set a reminder before the next expiry.

Did revoking sign me out of the dashboard?

It should not, and it does not. If a full sign-out genuinely coincided with a revocation, sign back in and report it to support with the time — see Contact Support. Do not include any remaining secrets in that message.

Should I revoke keys I am not sure about?

Yes. The cost of revoking a key that turned out to be in use is one redeploy. The cost of leaving a leaked key live is unbounded.