---
title: "Create a staged replacement private API key"
method: POST
path: "/v1/auth/keys/rotate"
tags: ["Auth"]
---

# Create a staged replacement private API key

`POST /v1/auth/keys/rotate`

## Request

- Base URL: `https://api.agentry.sh`
- URL: `https://api.agentry.sh/v1/auth/keys/rotate`
- Auth: HTTP bearer

Requires a stable Idempotency-Key. The current key remains active until explicit revocation. The replacement raw value is hash-only and returned once; exact retry identifies the prior replacement and confirms whether the old key remains active without minting again.

## Headers

- `Idempotency-Key` string, required

## Response `200`

OK

- object
  - `api_key` string, required
  - `key_id` string, required
  - `prefix` string, required
  - `user_id` string, required
  - `previous_key_id` string, required
  - `previous_key_active` boolean, required
  - `idempotent_replay` boolean, required
  - `next_action` string, required

## Other responses

- `409`: Exact retry identifies the hash-only replacement instead of returning or minting a secret
- `default`: Error

---

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