> ## 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.
# Rotate an API key
> Use the Regenerate action to issue a new key value with the same name, scope, and expiration — invalidating the old one — and roll your applications without downtime
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:
| Reason | Urgency |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| **Suspected leak** — key showed up in a commit, a log, a screenshot, a paste | **Immediate** — rotate first, investigate after |
| **Scheduled rotation** — your security policy requires every key to roll every 30 / 60 / 90 days | Planned |
| **Key is about to expire** — and you want to extend its life past the original expiration | Before expiry |
| **Departing team member** generated this key — even if it was scope-narrowed properly, prefer to start fresh | Same-day to following-week |
| **Prefix changed** — the old prefix shows up in audit-log searches you don't want to see anymore (rare) | Whenever convenient |
If a key is **definitely compromised** and you can't immediately deploy a replacement, **delete** it instead of rotating — see [Delete the key](#delete-the-key-revoke) 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.
**The old key is invalidated immediately when you confirm regeneration.** Any in-flight or new requests using the old key value start failing with `401 Unauthorized` the moment you click confirm. There is no overlap window — see the [no-downtime pattern](#no-downtime-rotation-pattern) below to avoid an outage.
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_` → `raff_`
* **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](/products/manage/team-projects/quickstart-guides/generate-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:
| Event | What it captures |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `apikey.update` (Regenerate) | Who clicked Regenerate, when, which key (by ID and name), the old prefix, the new prefix |
| `apikey.delete` | Who clicked Delete, when, which key (by ID and name), the prefix at deletion time |
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
Create the replacement key for a no-downtime rotation.
The key lifecycle and security model.
How keys authenticate against the API.