Skip to main content
API key rotation is an essential security practice that limits the blast radius of a compromised key.

​
How key rotation works

When you rotate an API key:
  1. A new key is generated — it is immediately active
  2. The old key receives an expiration date — it remains valid for the grace period you select, giving you time to update your services without downtime

​
Grace period options

OptionDescription
NowThe old key is immediately invalidated
In 1 hour
In 24 hours
In 3 days
In 7 days
If you need more time after rotation has started, you can extend the grace period from the key’s context menu using Change grace period.

​
Revoking keys

Revocation immediately invalidates a key (equivalent to setting the expiration to now). All requests using the revoked key return 401 Unauthorized. Default keys must be rotated before they can be revoked — this ensures there is always an active key for your environment.

​
Activity logging

All key lifecycle events are captured in the activity log:
  • Key created
  • Key rotated
  • Grace period changed
  • Key revoked
Events appear both in the key’s own Activity tab and in the global Logs > Activity view. For API-triggered actions, the actor is recorded as the API key ID.

​
Best practices

  1. Rotate keys regularly — periodic rotation reduces risk even if a key has not been compromised
  2. Use appropriate grace periods — allow enough time to update all services using the old key
  3. Monitor activity logs — review key events to detect unexpected access
  4. Use environment-specific keys — never share keys across environments
For full details on managing API keys, including scoped keys and client-side security:

API key management