Rotate a key immediately.

post

https://{host}:{port}/api/v3/key-management/keys/{kid}/rotations

Creates a successor key and atomically replaces {kid}.

The request body contains:

newKey: The successor key specification using unified KeyRequest format
acknowledgeCapabilityReduction (optional): Set to true to allow rotations
that reduce key capabilities (e.g., RSA with encrypt+sign → ML-DSA with sign only)

On success, returns 200 OK with the newly-created key metadata.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

kid

string

required

Body Params

JSON body containing the successor-key specification using unified KeyRequest format.

Parameters for immediate key rotation. The 'newKey' field specifies the successor key using the unified KeyRequest format. Use 'acknowledgeCapabilityReduction' to allow rotations that reduce key capabilities (e.g., from RSA with encrypt+sign to ML-DSA with sign-only).

newKey

object

required

Specification for the successor key using unified KeyRequest format.
The 'kty' field determines the key type:

Simple keys: oct, RSA, EC, ML-KEM, ML-DSA, etc.
Composite KEM: COMPOSITE_KEM_COMBINE
Composite Signature: COMPOSITE_SIGNATURE

acknowledgeCapabilityReduction

boolean

Set to true to acknowledge and accept capability reduction during rotation.
Required when rotating from a key with more capabilities to one with fewer
(e.g., losing encrypt/decrypt when rotating from RSA to ML-DSA).
If omitted or false and capability reduction would occur, the rotation fails.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

200Rotation executed; the successor key is returned.

400Invalid input: missing newKey, malformed payload, or capability reduction not acknowledged.

401Unauthorized: missing or invalid JWT token.

403Forbidden: authenticated user lacks the required scope.

404Key not found.

409Conflict: key is in an invalid state (e.g., already revoked).

413Payload Too Large: successor key parameters exceed limits.

500Internal Server Error.