---
title: "Reroll root key"
method: POST
path: "/v2/rootKeys.rerollKey"
tags: ["rootKeys"]
---

# Reroll root key

`POST /v2/rootKeys.rerollKey`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/rootKeys.rerollKey`
- Auth: HTTP bearer

Creates a new root key secret with the same name, enabled state, expiration, and
effective permissions as an existing root key in the authenticated workspace.
Requires `unkey:v1:<workspace_id>:rootKeys/<key_id>#write`, and the caller must
already hold every permission of the original key. When `expiration` is not null,
it also requires `unkey:v1:<workspace_id>:rootKeys/<key_id>#delete`.

`expiration` controls the original key: 0 revokes it immediately, a positive value
keeps it valid for that many milliseconds, and null keeps its current expiration.

## Request body

- V2RootKeysRerollKeyRequestBody
  - `keyId` string, required: Root key identifier returned by rootKeys.createKey or rootKeys.listKeys.
  - `expiration` integer, nullable, required: Milliseconds until the original root key expires. Use 0 to revoke it immediately. Use null to keep the original key's current expiration. This value never extends an existing expiration.

## Response `200`

Root key rerolled. Save the secret now; it cannot be retrieved later.

- V2RootKeysRerollKeyResponseBody
  - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2RootKeysRerollKeyResponseData, required
    - `keyId` string, required: Identifier of the new root key.
    - `key` string, required: New root key secret, returned only once. Store it securely.

## Other responses

- `400`: Invalid request.
- `401`: Authentication is required.
- `403`: The caller cannot reroll this root key or does not hold its permissions.
- `404`: The root key was not found.
- `429`: Too many requests.
- `500`: The root key could not be rerolled.

## Changes

- **2026-09-30** `2cf3cf769b2e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/rootKeys.rerollKey/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)