---
title: "Rotate a callback endpoint signing key"
method: POST
path: "/v1/endpoints/{endpointId}/signing-keys/rotate"
---

# Rotate a callback endpoint signing key

`POST /v1/endpoints/{endpointId}/signing-keys/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/endpoints/{endpointId}/signing-keys/rotate`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Creates the next endpoint signing key and selects it immediately for new deliveries while retaining the current key in the receiver acceptance set for a bounded overlap. The overlap defaults to and cannot exceed 24 hours. A second rotation is refused until the current overlap ends. The new secret is returned once to this call, so a call whose answer was never read has rotated a key the caller does not hold. It is recoverable: a signed-in member can read both keys, and the instant the overlap ends, through endpoints.revealSigningSecret. An API credential or an OAuth token cannot, so an integration that loses the answer needs a member to read it back rather than a second rotation, which is refused until the overlap ends. Send If-Match with the version the endpoint was read at to be refused rather than rotate an endpoint that has changed since.

## Path parameters

- `endpointId` string, required

## Headers

- `If-Match` string

## Request body

- object
  - `overlapSeconds` integer

## Response `201`

Rotate a callback endpoint signing key

- object
  - `endpoint` object, required
    - `headers` union[]
      - union
        - object
          - `name` string, required
          - `secret` false, required
          - `value` string, required
        - object
          - `name` string, required
          - `secret` true, required
          - `configured` true, required
        - object
          - `name` string, required
          - `suppressed` true, required
    - `createdAt` string, required
    - `disabledAt` string
    - `environmentKind` 'test' | 'live', required
    - `id` string, required
    - `name` string
    - `project` string, required
    - `signingKeys` object, required
      - `current` string, required
      - `next` object
        - `acknowledgedAt` string
        - `id` string, required
        - `overlapEndsAt` string, required
    - `status` 'active' | 'disabled', required
    - `updatedAt` string, required
    - `url` string, uri, required
    - `version` integer, required
  - `keyId` string, required
  - `secret` string, required
  - `shownOnce` true, 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, state_conflict, version_conflict.
- `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)