KMS key rotation

Key rotation creates a new key version while keeping previous versions available for decryption and verification. Rotation is a core part of cryptographic hygiene but does not require re-encrypting existing data.

How versions work

Each KMS key maintains versions 1 through N:

• New operations — Encrypt, sign, and HMAC use the latest version by default
• Existing data — Ciphertext and signatures embed the version used at creation time
• Decryption — KMS selects the correct version automatically from the embedded version marker
• Metadata — List and get responses include latestVersion, versions[], and minDecryptionVersion

After rotation, old ciphertext remains valid. You do not need to re-encrypt stored data.

Manual rotation

Trigger an immediate rotation with:

POST /v1/kms/{region}/keys/{id}/rotate

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  https://api.thalassa.cloud/v1/kms/nl-01/keys/app-encryption/rotate

The response includes updated version metadata. The new version becomes the latest for subsequent encrypt and sign operations.

Manual rotation requires update permission on the key. See Access control.

Automatic rotation

Configure automatic rotation at key creation or update the schedule later.

At create time

{
  "name": "rotating-key",
  "keyType": "aes256-gcm96",
  "keyRotationEnabled": true,
  "rotationPeriodInDays": 90
}

Update rotation settings

PATCH /v1/kms/{region}/keys/{id}/rotation

{
  "keyRotationEnabled": true,
  "rotationPeriodInDays": 180
}

Thalassa Cloud evaluates keys due for rotation hourly and rotates them in the background. Scheduled rotations emit kms.rotate.scheduled audit events.

Rotation on imported (BYOK) keys

Automatic and manual rotation on imported keys requires allowRotation: true at import time. If you did not set this flag during import, rotation is not available for that key.

See Bring your own key for import options.

Billing impact

Each key version is a separately metered unit from creation until the parent key is permanently deleted. Automatic rotation on a schedule increases version count over time and affects cost.

See Billing for metering details.

Audit events

Best practices

• Rotate symmetric encryption keys on a regular schedule aligned with your security policy
• Use automatic rotation for long-lived keys that protect production data
• Plan rotation frequency against billing: more frequent rotation means more versions
• Do not re-encrypt existing ciphertext after rotation unless your compliance policy requires it

See Best practices for additional security guidance.