Skip to main content
Unkey Docs

Key Rerolling

Rotate API keys in Unkey while preserving their configuration, permissions, and metadata. Set grace periods for seamless key transitions.
3 min read

What is Key Rerolling?#

Key rerolling (or key rotation) is the process of generating a new API key token while preserving all the configuration from an existing key. This is a critical security practice that allows you to regularly rotate credentials without disrupting your application's permissions or settings.

Why Reroll Keys?#

Key rerolling serves several important purposes:

  • Security Compliance: Many security frameworks require regular credential rotation
  • Compromise Recovery: Quickly replace keys that may have been exposed
  • Proactive Security: Regularly rotate keys as a preventive measure
  • Graceful Migration: Overlap periods allow zero-downtime key transitions

How Key Rerolling Works#

What Gets Copied#

When you reroll a key, the new key is an exact copy of the original in terms of configuration:

Preserved Settings:

  • Permissions and RBAC roles
  • Custom metadata fields
  • Rate limiting rules
  • Identity associations (for tracking usage across keys)
  • Remaining credits balance
  • Recovery/encryption settings
  • Keyspace association

What's New#

The rerolled key gets fresh values for:

  • Key ID (a new unique identifier)
  • API key token (the actual secret)
  • Creation timestamp

What Happens to the Original Key#

The original key remains active for a configurable grace period:

  • You specify the expiration duration (in milliseconds)
  • Set to 0 for immediate revocation
  • Common grace periods: 1 hour (3600000ms), 24 hours (86400000ms), 7 days (604800000ms)

Rotate a key from the dashboard#

You can rotate any active API key directly from the keys table without writing code.

  1. Open the keyspace and navigate to its Keys tab.
  2. Click the actions menu (...) on the key row and select Rotate key.
  3. Choose how long the old key should remain valid:
    • Revoke immediately
    • 1 minute, 15 minutes, 1 hour, 6 hours, or 24 hours
  4. Click Rotate key.
  5. Copy the new key secret from the success dialog and deliver it to the user. The plaintext is shown only once.

The new key inherits the original key's permissions, metadata, rate limits, credits, identity, and expiration (if any). The old key keeps verifying until the grace period elapses, then is revoked automatically. The grace period never extends past the original key's existing expiration.

Note

Expired keys cannot be rotated. The Rotate key action is disabled for keys that are past their expires timestamp.

Rotate a key with the API#

To reroll a key programmatically, make a POST request to /v2/keys.rerollKey:

Request Parameters#

  • keyId (required): The database identifier of the key to reroll (NOT the API key token)
  • expiration (required): Duration in milliseconds until the original key is revoked

Response#

Security Critical: The key field contains the actual API key token. This is the only time you'll receive it - Unkey stores only a hashed version. Never log or expose this value. Transmit it directly to the end user via secure channels only.

Common Use Cases#

Zero-Downtime Key Rotation#

For production systems that can't afford downtime:

  1. Reroll the key with a grace period (e.g., 24 hours)
  2. Deploy the new key to your systems
  3. Verify the new key is working
  4. The old key automatically expires after the grace period

Emergency Key Replacement#

When a key is compromised and needs immediate revocation:

Analytics and Usage Tracking#

An important aspect of key rerolling is that analytics remain consistent:

  • Key-level metrics: Each key has its own usage statistics
  • Identity-level metrics: If the original key has an identity, the new key inherits it
  • This allows you to track usage across both individual keys and the overall identity
  • Historical data from the original key remains accessible

Required Permissions#

Your root key needs the following permissions to reroll keys:

  • api.*.create_key or api.<api_id>.create_key
  • api.*.encrypt_key or api.<api_id>.encrypt_key (only when the original key is recoverable)

Limitations#

  • The new key uses the keyspace's default configuration for prefix and byte length
  • You cannot modify permissions or settings during reroll - use the update endpoint afterward if needed
Key RevocationDisabling Keys