Skip to main content

Documentation Index

Fetch the complete documentation index at: https://unkey.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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
  • API 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 API 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.
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: 
curl --request POST \
  --url https://api.unkey.com/v2/keys.rerollKey \
  --header 'Authorization: Bearer <ROOT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "expiration": 86400000
  }'

​
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

{
  "meta": {
    "requestId": "req_abc123def456"
  },
  "data": {
    "keyId": "key_3dHLcNyRzJaiDyo2Jekz9r",
    "key": "prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT"
  }
}

​
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
# Give 24 hours for migration
curl --request POST \
  --url https://api.unkey.com/v2/keys.rerollKey \
  --header 'Authorization: Bearer <ROOT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "expiration": 86400000
  }'

​
Emergency Key Replacement

When a key is compromised and needs immediate revocation: 
# Revoke immediately
curl --request POST \
  --url https://api.unkey.com/v2/keys.rerollKey \
  --header 'Authorization: Bearer <ROOT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "expiration": 0
  }'

​
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 API’s default configuration for prefix and byte length
  • You cannot modify permissions or settings during reroll - use the update endpoint afterward if needed
Last modified on May 8, 2026