---
title: "Replace one of your API keys with a new secret"
method: POST
path: "/v1/keys/{id}/rotate"
---

# Replace one of your API keys with a new secret

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

## Request

- Base URL: `https://agentmandate-api.com`
- URL: `https://agentmandate-api.com/v1/keys/{id}/rotate`
- Auth: HTTP bearer

Issues a replacement key and revokes the old one. This is the answer to a leaked or lost key: the new secret is returned once, the old secret stops working immediately, and the label carries over unless you supply a new one. The replacement is issued at your account's current allowance — your paid plan if you have one — not at the old key's. Rotating does not count against the active-key limit, because it replaces rather than adds. Free, and it works while you are out of quota.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string: Optional new label. Defaults to the old key's.

## Response `201`

Success

- object
  - `apiKey` string: The new secret. Shown once.
  - `keyId` string
  - `replaced` string: The id of the key that was revoked.
  - `product` string
  - `quotaPerPeriod` integer, nullable
  - `plan` string
  - `warning` string
  - `requestId` string

## Other responses

- `400`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `401`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `404`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `429`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `500`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.

---

[API](https://skmtc.dev/agentmandate-api/apis/agent-mandate.md) · [All operations](https://skmtc.dev/agentmandate-api/apis/agent-mandate/llms.txt) · [OpenAPI document](https://skmtc.dev/agentmandate-api/apis/agent-mandate/revisions/463fe122c4d8?raw)