What is key rotation?
Key rotation replaces an existing API key with a new one while keeping the old key active for a short overlap window. In the current dashboard flow, that overlap window is 24 hours.How rotation works
New key created
BabySea creates a replacement key with the same name, scopes, and IP allowlist as the original key.
24 hour overlap begins
The original key continues to work for 24 hours so you can update your applications without an immediate break.
Copy the new key
After success, BabySea opens the confirmation view with the title Key rotated successfully and shows the new key one time.
Update your services
Replace the old key in all your services, environment variables, and secrets managers with the new key.
What the rotation dialog says
Before you confirm rotation, the dialog description says:This will create a new key to replace: {name}. The old key will continue to work for 24 hours, giving you time to update your applications. After the grace period, the old key will stop working automatically.
The confirm action is Rotate key.
What is preserved
The replacement key inherits these properties from the original key:| Property | Inherited |
|---|---|
| Name | Yes |
| Scopes | Yes |
| IP allowlist | Yes |
Dashboard indicators
After rotation, the Status column reflects the key state:| Key state | Status shown |
|---|---|
| New key | Active |
| Old key during the 24 hour overlap | Rotated |
| Old key after the overlap ends | Expired |
| Manually disabled key | Revoked |
Rotated instead of another rotate action.
Rotation rules
| Rule | Detail |
|---|---|
| Only active keys can rotate | Revoked, expired, and already rotated keys cannot start another rotation. |
| One rotation at a time | The old key keeps a rotated marker, so the dashboard does not offer another rotate action for that row. |
| Owner access required | Members can view the page but cannot rotate keys. |
Example workflow
A typical quarterly rotation for a production key:- Monday 10:00 AM: Rotate the
prod-api-workerkey in the dashboard. Copy the new key. - Monday 10:05 AM: Update the key in your secrets manager (Vercel, AWS, Vault, etc.).
- Monday 10:10 AM: Deploy your services. They pick up the new key from the secrets manager.
- Monday 10:30 AM: Verify the new key is working with
GET /v1/statusor a normal application request. - Tuesday 10:00 AM: Grace period expires. The old key stops working. No action needed.
Rotation vs. revocation
| Action | Old key | New key created | Use case |
|---|---|---|---|
| Rotate | Active during grace | Yes | Planned key refresh |
| Revoke | Immediately disabled | No | Compromised or leaked key |
Revoke a key
Revoking a key immediately disables it. All requests using the revoked key returnBSE1002 with HTTP 401 from the moment of revocation.
| Detail | Value |
|---|---|
| Effect | Immediate (key stops working instantly) |
| Reversible | No |
| Logs preserved | Yes (API key logs remain until the key is deleted) |
| When to use | Key is compromised, leaked, or no longer needed |
Delete a key
Deleting a key permanently removes it and all associated API key logs. The key is also immediately revoked if it was still active.| Detail | Value |
|---|---|
| Effect | Immediate removal of key and all logs |
| Reversible | No |
| Logs preserved | No (logs are removed with the key) |
| When to use | Cleaning up old keys you no longer need to audit |
Before deleting, consider whether you still need the API logs for auditing. If you only want to stop the key from working, revoke it instead.
Action availability
Not all actions are available for every key status:| Action | Active | Rotated | Expired | Revoked |
|---|---|---|---|---|
| Rotate | Yes | No | No | No |
| Revoke | Yes | Yes | No | No |
| Delete | Yes | Yes | Yes | Yes |