> ## 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.

# Key Rerolling

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

## 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.
</Note>

## Rotate a key with the API

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

```bash theme={"theme":"kanagawa-wave"}
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

```json theme={"theme":"kanagawa-wave"}
{
  "meta": {
    "requestId": "req_abc123def456"
  },
  "data": {
    "keyId": "key_3dHLcNyRzJaiDyo2Jekz9r",
    "key": "prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT"
  }
}
```

<warning>
  **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.
</warning>

## 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

```bash theme={"theme":"kanagawa-wave"}
# 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:

```bash theme={"theme":"kanagawa-wave"}
# 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 keyspace's default configuration for prefix and byte length
* You cannot modify permissions or settings during reroll - use the update endpoint afterward if needed