---
title: "Rotate a KMS key immediately"
method: POST
path: "/{tenantId}/kms/providers/{providerId}/keys/{keyAlias}/rotations"
tags: ["Rotations"]
---

# Rotate a KMS key immediately

`POST /{tenantId}/kms/providers/{providerId}/keys/{keyAlias}/rotations`

Performs an immediate key rotation. If `targetProviderId` is omitted the replacement key is created in the current provider. If `targetProviderId` is supplied, rotation is also the cross-KMS migration mechanism: the replacement key is generated in the target provider and active assignments are transferred without exporting private key material.

## Request body

- RotateKmsKeyArgs — Request body for immediate key rotation. Path parameters supply tenant, provider, and key alias.
  - `targetProviderId` string, nullable — Target provider for cross-KMS rotation. If omitted, the current provider is used.
  - `baseAlias` string, nullable — Base alias used when the server generates a timestamped replacement alias.
  - `newAlias` string, nullable — Explicit alias for the replacement key.
  - `rotationInterval` string, nullable — ISO-8601 duration to carry forward for recurring rotation.

## Response `200`

Rotation record and transferred assignments.

- RotateKmsKeyResult
  - `rotation` KmsKeyRotationRecord, required — Record of a same-provider rotation or cross-provider migration rotation.
    - `rotationId` string, required
    - `tenantId` string, required
    - `oldKey` KmsKeyRef, required — Reference to a managed KMS key.
      - `providerId` string, required
      - `keyAlias` string, required
    - `newKey` KmsKeyRef, required — Reference to a managed KMS key.
      - `providerId` string, required
      - `keyAlias` string, required
    - `targetProviderId` string, required
    - `rotatedAssignments` string[]
    - `createdAssignments` string[]
    - `rotationInterval` string, nullable — ISO-8601 duration used for recurring rotation.
    - `rotateAt` string, date-time, nullable
    - `status` 'ACTIVE' | 'ROTATING' | 'ROTATED' | 'REVOKED' | 'DEPRECATED', required — Lifecycle status for a KMS key or rotation record.
    - `createdAt` string, date-time, nullable
    - `updatedAt` string, date-time, nullable
  - `oldAssignments` KmsKeyAssignment[], required
    - `assignmentId` string, required
    - `tenantId` string, required
    - `providerId` string, required
    - `keyAlias` string, required
    - `classification` 'PLATFORM' | 'TENANT' | 'APPLICATION' | 'SERVICE', required — Operational ownership scope for tenant-managed infrastructure resources.
    - `serviceType` string, nullable
    - `serviceInstance` string, nullable
    - `partyId` string, nullable
    - `relationshipType` string, nullable
    - `purpose` string, required
    - `validFrom` string, date-time, nullable
    - `validUntil` string, date-time, nullable
    - `status` 'ACTIVE' | 'ROTATED' | 'REVOKED' | 'INACTIVE', required — Lifecycle status for a key assignment.
    - `targetProviderId` string, nullable
    - `createdAt` string, date-time, nullable
    - `updatedAt` string, date-time, nullable
  - `newAssignments` KmsKeyAssignment[], required
    - `assignmentId` string, required
    - `tenantId` string, required
    - `providerId` string, required
    - `keyAlias` string, required
    - `classification` 'PLATFORM' | 'TENANT' | 'APPLICATION' | 'SERVICE', required — Operational ownership scope for tenant-managed infrastructure resources.
    - `serviceType` string, nullable
    - `serviceInstance` string, nullable
    - `partyId` string, nullable
    - `relationshipType` string, nullable
    - `purpose` string, required
    - `validFrom` string, date-time, nullable
    - `validUntil` string, date-time, nullable
    - `status` 'ACTIVE' | 'ROTATED' | 'REVOKED' | 'INACTIVE', required — Lifecycle status for a key assignment.
    - `targetProviderId` string, nullable
    - `createdAt` string, date-time, nullable
    - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Bad request due to invalid input parameters or request body.
- `404` — The requested resource was not found.
- `409` — The requested operation conflicts with the current KMS lifecycle state, active assignments, deletion protection, or migration/rotation state.
- `500` — An unexpected error occurred on the server.

---

[API](https://skmtc.net/sphereon-opensource/apis/kms-rest-server-api.md) · [All operations](https://skmtc.net/sphereon-opensource/apis/kms-rest-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sphereon-opensource/kms-rest-server-api/revisions/e9136cbde1c1/schema)