---
title: "Roll API key"
method: POST
path: "/v1/auth/keys/{keyId}/roll"
tags: ["Auth"]
---

# Roll API key

`POST /v1/auth/keys/{keyId}/roll`

Replaces the key secret while keeping its name and identity in the key list. The previous secret stops working immediately. The new secret is minted with the current plan tier rate limit and is returned only once. Requires an owner or admin session/OAuth principal; API keys cannot roll themselves.

## Path parameters

- `keyId` string, required

## Query parameters

- `organizationId` string

## Response `200`

The rolled key. The plaintext secret is returned only once.

- object
  - `success` true, required
  - `data` CreateApiKeyResult, required
    - `key` string, required
    - `keyId` string, required

## Other responses

- `400` — The request payload or parameters are invalid.
- `401` — Authentication is missing, invalid, or expired.
- `402` — The requested operation requires a paid plan. API access (organization API keys) requires the Starter plan or higher; a downgraded organization receives this error until its plan is restored.
- `403` — The authenticated principal cannot access the resource.
- `404` — The requested resource was not found.
- `429` — The rate limit was exceeded. API key limits are set by plan tier (Starter 600/min, Pro 1500/min, Enterprise 3000/min). Check the Retry-After header before retrying.
- `500` — An unexpected internal error occurred.

---

[API](https://skmtc.dev/inth/apis/inth-api.md) · [All operations](https://skmtc.dev/inth/apis/inth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inth/inth-api/revisions/97262bd49ddd/schema)