Rotate an API key

Documentation Index

Fetch the complete documentation index at: https://docs.rafftechnologies.com/llms.txt

Use this file to discover all available pages before exploring further.

_{Updated May 8, 2026} Rotation is replacing a key’s secret value while keeping its identity (name, role assignments, projects, expiration) the same. The dashboard’s Regenerate action does this in one click: a new key value is issued, the old value is immediately invalidated, and you copy the new value once. This page covers how to rotate, when to rotate, and the no-downtime pattern for switching applications over.

​

When to rotate

The most common reasons: If a key is definitely compromised and you can’t immediately deploy a replacement, delete it instead of rotating — see Delete the key below. Deletion stops authentication immediately at the cost of dropping every active request.

​

1. Open the API Keys list

In the left sidebar, open API Keys. Find the key by name and look at its row’s right-hand actions. The 🔄 Regenerate icon (cycle arrows) is the rotation action. Click it.

​

2. Confirm regeneration

A confirmation dialog asks you to type the key’s name (or click confirm — depending on the dialog version). Once you proceed, the API Key Created dialog opens with the new key value — same shape as the post-create dialog. Copy the new key now (it has the same raff_ prefix as before but a different suffix) into your secret store. Click Done when you’ve safely copied it.

​

3. What rotation keeps and what it changes

Same:

• Name
• Account Role and Project Role assignments — and the projects they apply to
• Expiration setting — if the key was originally configured for “1 year”, the rotated key gets a fresh 1-year window from the rotation timestamp; if it was “Never expires”, the rotated key never expires either
• Audit-log identity — the rotated key keeps the same internal ID, so old audit-log entries still resolve to “this key” (just with a different value)

Changes:

• Key value — raff_<old-suffix> → raff_<new-suffix>
• Key prefix shown in the list — the new prefix replaces the old one
• Last Used — resets to Never until the new key starts being used

If you need to change the role or project access, regenerate doesn’t help — that’s frozen on the key. The fix is to delete this key and create a new one with the right scope.

​

No-downtime rotation pattern

Because regenerate has no overlap window, the simplest no-downtime rotation uses two keys for a brief period, not regeneration of one. The pattern:

1. Create a new key (Generate an API key) with the same scope as the one you want to rotate. Give it a slightly different name (Production CI v2).
2. Deploy the new key to every system that uses the old one — secret store update, app redeploy, CI variable change.
3. Wait for the deploy to roll out everywhere — check Last Used on both keys; once the new key has a recent Last Used and the old key doesn’t, the deploy is complete.
4. Delete the old key from its row’s red trash icon. Any straggling traffic to the old key starts failing immediately, but at this point everything has switched over.

This adds one step over Regenerate but eliminates the no-overlap-window risk. For production rotations, this pattern is worth the extra step. For low-stakes rotations (dev environments, single-process scripts), Regenerate in place is fine — the few seconds of 401 errors during the deploy don’t matter.

​

Delete the key (revoke)

To stop a key from authenticating immediately without issuing a replacement, click the 🗑️ Delete icon on the row. A confirmation asks you to type the name; once confirmed, the key is gone and any request using it returns 401. Use Delete when:

• The key is definitely compromised and you can’t roll out a replacement quickly enough
• The integration that owned the key is decommissioned
• You created a key by mistake (wrong scope, wrong name) and want to start over

Deletion is final. There’s no recovery — the key value cannot be retrieved, and the audit-log entries continue to reference the deleted key by ID. Recreate from scratch if you need an equivalent key.

​

What about existing requests in flight?

Both Regenerate and Delete invalidate the old key the moment they complete. Any HTTP request that’s already established a TCP connection but hasn’t yet sent its X-API-Key header will fail with 401. Long-running connections (WebSockets, streaming responses) continue if the auth was already validated, but reconnecting will fail. In practice this means: rotation/deletion drops to the floor any traffic mid-flight at the moment you click confirm. Plan rotations during low-traffic windows, or use the no-downtime pattern above.

​

Audit logging

Every regeneration and deletion is recorded in the account audit log: If you ever need to prove “this key was rotated on date X by member Y”, the audit log has it. Account members with account.audit.view (Owner and Admin by default) can read these entries.

​

Related