---
title: "Rotate ONE key; sibling keys of the same kind keep working"
method: POST
path: "/credits/tenants/me/keys/{keyId}/rotate"
tags: ["Tenants"]
---

# Rotate ONE key; sibling keys of the same kind keep working

`POST /credits/tenants/me/keys/{keyId}/rotate`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/tenants/me/keys/{keyId}/rotate`
- Auth: HTTP bearer

The replacement inherits the target's name, scopes, endpoint allowlist, pricing, audience (legacy policy-bearing rows are normalized to the execution audience), and — unless expiresIn is passed — its expiry deadline. A human caller cannot rotate a secret key whose inherited scopes include authority absent from their own effective membership scopes. Only the target is superseded: with gracePeriodSeconds > 0 it keeps authenticating until the overlap ends (capped at the target's own expiry), otherwise it is revoked with this response. Rotating a key that is already rotating out is rejected (rotate its replacement instead), as is rotating an expired key without a fresh expiresIn. This is the rotation the dashboard uses; the kind-level /keys/rotate remains the rotate-everything cutover. Requires a workspace owner or admin with MFA or passkey step-up completed in the last ten minutes.

## Path parameters

- `keyId` string, uuid, required

## Headers

- `X-Locus-Step-Up` string, password

## Request body

- object
  - `gracePeriodSeconds` integer: Overlap during which the old key still works. Omitted or 0 means it dies with this response.
  - `expiresIn` integer: Lifetime of the replacement in seconds. Omit to inherit the target's deadline.

## Response `200`

New raw key (returned exactly once) with keyMetadata.

## Other responses

- `400`: Target is revoked, already rotating out, expired without a fresh expiresIn, carries a secret scope the acting member does not hold — or an unknown body field.
- `403`: STEP_UP_REQUIRED or INSUFFICIENT_SCOPE.
- `404`: No such key in this workspace (malformed ids included).

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)