---
title: "Rotate an API key"
method: POST
path: "/v1/keys/{key_id}/rotate"
---

# Rotate an API key

`POST /v1/keys/{key_id}/rotate`

## Request

- Base URL: `https://api.reqbeat.com`
- URL: `https://api.reqbeat.com/v1/keys/{key_id}/rotate`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Agent-driven key rotation: mints a replacement key bound to the SAME
account and revokes `key_id` in one call -- an autonomous agent rotates
its own credential without an operator or a human seat in the loop, so
usage keeps billing to the account. Scoped to the caller's own
customer; `key_id` need not be the presented key. 404 for an id that
doesn't exist, belongs to another tenant, or is already revoked --
indistinguishable, same as `delete_key`.

`scopes`, omitted, keeps `key_id`'s own scopes -- rotation replaces a
credential, it never widens a narrowed one. Requested or kept, they must
be a subset of the PRESENTING key's scopes (`key_id` need not be the
presenting key), else 403 naming the excess.

Requires the `account` scope.

## Path parameters

- `key_id` integer, required: The API key's id, as returned by GET /v1/keys.

## Request body

- RotateKeyRequest
  - `scopes` string[], nullable

## Response `201`

Successful Response

- IssueKeyResponse
  - `id` integer, required
  - `key` string, required
  - `customer_id` string, required
  - `account_id` integer, required
  - `tier` string, required
  - `scopes` string[], required

## Other responses

- `401`: No API key was sent.
- `403`: The presented key is invalid or revoked, or (see `x-required-scope` on this operation) it does not carry the scope this operation requires.
- `422`: Validation Error

---

[API](https://skmtc.dev/reqbeat/apis/reqbeat-api.md) · [All operations](https://skmtc.dev/reqbeat/apis/reqbeat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reqbeat/apis/reqbeat-api/revisions/4758e5957e8c?raw)