Skip to main content
Rerolling gives a key a new secret and keeps its settings. Unkey creates a new key with the same settings, and the old key keeps working for a grace period you choose. Use it for scheduled rotation, after a suspected leak, or when a user asks for a fresh key.
Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. See Permission reference for every permission.
The root key must grant write on the original key: unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write. A matching wildcard grant also satisfies this requirement. The same permission applies to recoverable keys. See Root key permissions.

Request

string
required
The identifier of the key to reroll (key_...), not the key string itself.
integer | null
required
Milliseconds from now until the old key stops working. The maximum is 4102444800000. The time is rounded up to the next whole minute, so expiration: 1 can leave the old key working for up to a minute. Only 0 revokes it immediately. Set it to null to keep the old key working; it keeps its current expiry, if it has one.

Response

key is the new key, and this is the only time it’s returned. keyId is the new key’s ID. The old key keeps its own keyId until it expires.

What the new key copies

The new key copies the old key’s enabled state, name, metadata, identity, expiry, credits and refill schedule, roles, permissions, and rate limits. If the old key was recoverable, so is the new one. The new key gets a new keyId and secret. It keeps the old key’s prefix, or uses the keyspace’s default prefix if it had none. Its length is the keyspace’s current default, or 16 bytes if none is set, so a key created with a custom byteLength can change length. Analytics by identity carry on across the reroll. Analytics by keyId start fresh for the new key.

What happens to the original

The old key’s expiry becomes now plus expiration, rounded up to the next minute. With null, the old key’s expiry does not change. With 0, its next verification returns code: EXPIRED. The API applies the grace period even if the old key was due to expire sooner, so a reroll can extend its life. Check the old key’s expires first if that matters. You can’t reroll a key that has already expired. The API returns HTTP 400 err:unkey:application:invalid_input and creates no new key. This includes an old key you rerolled with expiration: 0, so reroll the replacement key instead. A key that hasn’t expired yet, including one still in its grace period, can be rerolled again. The event is recorded in the audit log as key.reroll.

From the dashboard

Choose Rotate key from the key’s actions menu. Pick a grace period: revoke immediately, 15 minutes, 1 hour, 6 hours, 24 hours (the default), or Do not expire original key. That last option keeps the old key working with its current expiry. You can’t rotate an expired key from the dashboard. A grace period can extend the original key’s expiry, just as it can through the API. The new key is shown once.
Rotate key dialog with the grace period dropdown open, from Revoke immediately to 24 hours

Reroll or reissue

Reroll when the user should keep working without a break. keys.rerollKey can’t change settings, so to change them too, update the new key with keys.updateKey afterward, or create a new key and delete the old one.
Last modified on November 12, 2026