Skip to main content

​
What is key rotation?

Key rotation replaces an existing API key with a new one while keeping the old key active for a temporary overlap window. BabySea calls that overlap window the grace period. In the current dashboard, you can choose a grace period from 1 hour to 168 hours. The select defaults to 24 hours.

​
How rotation works

1

Start rotation

In the API keys table, open the row action menu and click Rotate.
2

Choose Grace period

In the dialog Rotate API key, choose Grace period. The available values are 1 hour, 6 hours, 12 hours, 24 hours (default), 48 hours (2 days), 72 hours (3 days), and 168 hours (7 days).
3

New key created

BabySea creates a replacement key with the same name, scopes, and IP allowlist as the original key.
4

Grace period begins

The original key keeps working until the selected grace period ends, so you can update your applications without an immediate break.
5

Copy the new key

After success, BabySea opens the confirmation view Key rotated successfully and shows the new key one time.
This is the only time the new key is shown. Store it securely before closing the dialog.
6

Update your services

Replace the old key in all your services, environment variables, and secrets managers with the new key.
7

Old key stops working

After the selected grace period ends, the old key no longer authenticates requests.

​
What the rotation dialog says

Before you confirm rotation, the dialog explains that BabySea will create a replacement key, keep the old key active during the selected grace period, and stop the old key automatically after that period. The confirm action is Rotate key. The secondary action is Cancel. After rotation, the success view shows:
  • the title Key rotated successfully
  • the field label New API key
  • Show value and Hide value
  • a copy button
  • the action Done

​
What is preserved

The replacement key inherits these properties from the original key:
PropertyInherited
NameYes
ScopesYes
IP allowlistYes

​
Dashboard indicators

After rotation, the Status column reflects the key state:
Key stateStatus shown
New keyActive
Old key during the grace periodRotated
Old key after the overlap endsExpired
Manually disabled keyRevoked
The row action menu also changes with state. For example, already rotated keys show Rotated instead of another rotate action.

​
Rotation rules

RuleDetail
Only active keys can rotateRevoked, expired, and already rotated keys cannot start another rotation.
One rotation at a timeThe old key keeps a rotated marker, so the dashboard does not offer another rotate action for that row.
Grace period boundsThe selected grace period must be between 1 and 168 hours.
Owner access requiredTeam members can view the page but cannot rotate keys.

​
Example workflow

A typical quarterly rotation for a production key using the default value:
  1. Monday 10:00 AM: Rotate the prod-api-worker key in the dashboard. Copy the new key.
  2. Monday 10:05 AM: Update the key in your secrets manager.
  3. Monday 10:10 AM: Deploy your services. They pick up the new key from the secrets manager.
  4. Monday 10:30 AM: Verify the new key is working with GET /v1/status or a normal application request.
  5. Tuesday 10:00 AM: Grace period expires. The old key stops working. No action needed.
Schedule a reminder before the selected grace period ends so you can confirm every application is already using the new key.

​
Rotation vs. revocation

ActionOld keyNew key createdUse case
RotateActive during grace periodYesPlanned key refresh
RevokeImmediately disabledNoCompromised or leaked key
If a key is compromised, do not rotate. Revoke it immediately to disable it, then create a new key. See Revoke a key below.

​
Revoke a key

Revoking a key immediately disables it. All requests using the revoked key return BSE1002 with HTTP 401 from the moment of revocation. The confirmation dialog is Revoke API key. Its confirm action is Revoke key.
DetailValue
EffectImmediate, the key stops working at once
ReversibleNo
Logs preservedYes, until the key is deleted
When to useKey is compromised, leaked, or no longer needed
Revocation cannot be undone. If you need the key’s functionality back, create a new one.

​
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. The confirmation dialog is Delete API key. Its confirm action is Delete key.
DetailValue
EffectImmediate removal of the key and all associated key logs
ReversibleNo
Logs preservedNo
When to useCleanup when you no longer need the key or its audit trail
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:
ActionActiveRotatedExpiredRevoked
RotateYesNoNoNo
RevokeYesYesNoNo
DeleteYesYesYesYes
All key management actions are available from the three-dot menu in the API keys table.