Skip to main content

​
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)

​
Making a Reroll Request

To reroll a key, 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