Skip to main content
Rotation creates a new material version under the same key ID and CRN. IAM policies, tags, and applications that reference the key keep working. AES-256, RSA-2048, RSA-4096, and ECDSA-P256 customer keys support both automatic and on-demand rotation. Platform-managed system keys have their own lifecycle. Older material remains available for decryption and signature verification. Rotation does not rewrite stored ciphertext, generate replacement data keys, or revoke older signatures. Deleting the key eventually destroys all its versions.
The CLI examples require basaltic v0.26.0 or later. The Go examples require sdk-go v0.30.0 or later.

​
Configure automatic rotation

Automatic rotation is off by default. Choose a period of 90–2560 whole days; omitting rotation_period_days selects 365 days. The first rotation becomes due one period after enabling. Changing the period resets that date; saving an unchanged policy preserves it.
Open KMS, select your key, and open Key rotation. In Automatic rotation, choose Enabled, set Rotation period (days), and choose Save. The card shows the current material version and next scheduled rotation.
Set enabled to false to stop automatic rotation. Send the existing period too if you want to retain it. This cancels automatic requests that have not started; a dispatched rotation can still complete. Only enabled customer keys can change their policy or rotate. A disabled key keeps its schedule but is skipped. When re-enabled, an overdue schedule produces one rotation and resumes its original cadence. Cancelling key deletion returns the key disabled; enable it to resume rotation.

​
Rotate now

An on-demand rotation leaves the automatic schedule unchanged. Generate one request token for the logical rotation and reuse it for every retry, including after a timeout. The token stays associated with that rotation for the lifetime of the key. Omitting it makes each request a new rotation intent.
In KMS, open the key and Key rotation, then choose Rotate now. Confirm Rotate key material. Open the Version history tab to check the result in the full-width table.

​
Check progress and history

200 returns a completed or cancelled request. 202 means the request is durably accepted and still pending, in progress, or awaiting reconciliation. Poll by rotation ID. History is newest first; use meta.marker as the next marker while meta.has_more is true.
If reconciliation_required persists, contact support with the key ID and rotation ID. Reusing another request token does not resolve it. A different rotation request while work is active returns 409 KMS_ROTATION_IN_PROGRESS.

​
Rewrap stored ciphertext

Existing ciphertext decrypts without migration. To move a ciphertext or wrapped data key to the current material version, call rewrap with the same key and store the returned ciphertext. No plaintext is returned. For an envelope encrypted with AAD, the original AAD and encrypted payload stay unchanged; you still need that AAD to decrypt. Rewrap does not validate the envelope payload or its AAD.
The console manages rotation policies and history. Rewrap stored ciphertext through the API, CLI, or SDK.

​
Signatures and public keys

Persist key_version returned by Sign alongside the signature and algorithm. Pass it to Verify or to GET /v1/keys/{key_id}/public-key?key_version=1 when verifying offline. Omitting the version on Verify tries retained public-key versions for compatibility with older signatures. Omitting it on public-key retrieval returns the current public key, which may differ from the key that signed an older message. See signing and verifying and KMS permissions. Rotation management, signing, public-key retrieval, and rewrap use separate IAM actions.