---
title: "Rotate an API credential"
method: POST
path: "/v1/credentials/{credentialId}/rotate"
---

# Rotate an API credential

`POST /v1/credentials/{credentialId}/rotate`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/credentials/{credentialId}/rotate`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Replaces a credential with a new one and gives the original a deadline, so consumers can pick up the new secret before the old stops working. The replacement is a new credential with its own identifier and the same authority and scopes; the original keeps working until it expires, then refuses with `credential_expired` rather than `credential_revoked`. `overlapSeconds` may only shorten the window — the default is also the maximum — and zero retires the original immediately. The new secret is in this response and in no other. Some calls need more: credentials:administer is required as well when the target was not created by the caller, and the call is refused `scope_missing` without it.

## Path parameters

- `credentialId` string, required

## Request body

- object
  - `overlapSeconds` integer

## Response `201`

Rotate an API credential

- object
  - `credential` object, required
    - `createdAt` string, required
    - `displayPrefix` string, required
    - `environmentKind` 'test' | 'live', required
    - `expiresAt` string
    - `id` string, required
    - `issuedBy` string
    - `lastUsedAt` string
    - `project` string, required
    - `revokedAt` string
    - `supersededBy` string
    - `scopes` string[], required
    - `secret` string, required
    - `shownOnce` true, required
  - `retired` object, required
    - `createdAt` string, required
    - `displayPrefix` string, required
    - `environmentKind` 'test' | 'live', required
    - `expiresAt` string
    - `id` string, required
    - `issuedBy` string
    - `lastUsedAt` string
    - `project` string, required
    - `revokedAt` string
    - `supersededBy` string
    - `scopes` string[], required

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing.
- `404`: Problem document. Possible codes at this status: not_found.
- `409`: Problem document. Possible codes at this status: project_archived.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)