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

# Reroll portal key

`POST /v2/portal.rerollKey`

Reroll an API key owned by the authenticated portal session's end user,
issuing a new key while preserving its configuration.

This is the portal-scoped variant of `keys.rerollKey`. It authenticates only
with a portal session cookie and may only reroll keys owned by the session's
external identity; any other key returns 404.

## Request body

- V2KeysRerollKeyRequestBody
  - `keyId` string, required — The database identifier of the key to reroll. This is the unique ID returned when creating or listing keys, NOT the actual API key token. You can find this ID in: - The response from `keys.createKey` - Key verification responses - The Unkey dashboard - API key listing endpoints
  - `expiration` integer, required — Duration in milliseconds until the ORIGINAL key is revoked, starting from now. This parameter controls the overlap period for key rotation: - Set to `0` to revoke the original key immediately - Positive values keep the original key active for the specified duration - Allows graceful migration by giving users time to update their credentials Common overlap periods: - Immediate revocation: 0 - 1 hour grace period: 3600000 - 24 hours grace period: 86400000 - 7 days grace period: 604800000 - 30 days grace period: 2592000000

## Response `200`

Key rerolled successfully. The new plaintext key is returned exactly once.

- V2KeysRerollKeyResponseBody
  - `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` V2KeysRerollKeyResponseData, required
    - `keyId` string, required — The unique identifier for the newly created key. This is NOT the actual API key token, but a reference ID for management operations. Store this ID to: - Update or revoke the key later - Track the key in your database - Display in admin dashboards (safe to log) Note: This is a new ID - the original key retains its own ID.
    - `key` string, required — The newly generated API key token (the actual secret that authenticates requests). **SECURITY CRITICAL:** - This is the only time you'll receive the complete key - Unkey stores only a hashed version (unless the original key was created with `recoverable=true`) - Never log, store, or expose this value in your systems - Transmit directly to the end user via secure channels only - If lost and not recoverable, you must reroll or create a new key The key format follows: `[prefix]_[random_bytes]` - Prefix is extracted from the original key or uses API default - Random bytes follow API configuration (default: 16 bytes) This is NOT the keyId - it's the actual secret token used for authentication.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/060c53b503ce/schema)