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

# Roll API key

`POST /v1/api-keys/{keyId}/roll`

## Request

- Base URL: `https://api.inth.com`
- URL: `https://api.inth.com/v1/api-keys/{keyId}/roll`
- Auth: HTTP bearer

Replaces the secret of a key while keeping its name and ID in the key list. The previous secret stops working immediately. The new secret is minted with the current plan rate limit and is returned only once. Requires api-keys.write, a user token, and an admin or owner role; 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` ApiKeySecret, required
    - `id` string, required
    - `key` string, required: The plaintext secret. Returned once; store it now.

## Other responses

- `400`: The request payload or parameters are invalid.
- `401`: Authentication is missing, invalid, or expired.
- `403`: The credential is valid but may not perform the operation. `INSUFFICIENT_SCOPE`: the credential was never granted the capability the operation needs. `details.requiredScope` names it, and the `WWW-Authenticate` header carries `Bearer error="insufficient_scope"`. An OAuth client fixes this by requesting the scope; an organization API key cannot gain it. `FORBIDDEN`: the capability is present but the membership behind the credential lacks the role, or the resource belongs to another organization.
- `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.

## Changes

- **2026-09-08** `66c8f6ac2730`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/inth/apis/inth-api/changes/v1/api-keys/:keyId/roll/post.md)

---

[API](https://skmtc.dev/inth/apis/inth-api.md) - [All operations](https://skmtc.dev/inth/apis/inth-api/llms.txt) - [OpenAPI document](https://skmtc.dev/inth/apis/inth-api/revisions/5a1be8d43402?raw)