Skip to main content
POST/vault/keys/{key_id}/rotate

Rotate Key

Creates a new version of the project's platform KEK and re-wraps every data key under it.

Values are never decrypted to do it.

If the re-wrap fails, the old version stays active.

One rotation or custody change runs at a time per project.

Needs PROJECT_ADMIN.

Parameters
projectId *query

The project's id.

key_id *path

The project's active KEK.

Responses
HTTPK9O CodeDescription
200The key was rotated: every data key is wrapped under the new version.
401The request carries no authenticated caller.
403The caller isn't a `PROJECT_ADMIN` of the project.
409`K9O_KEY_NOT_ACTIVE`: the key isn't the active one. `K9O_KEY_ROTATION_IN_PROGRESS`: a rotation is already running. `K9O_REKEY_CUSTOMER_KEY`: the customer holds the project's keys, so rotate them at the customer's key service.
500`K9O_REKEY_FAILED`: the re-wrap failed, and the old version stays active.
501`K9O_REKEY_UNSUPPORTED`: the project's key backend can't create a new version.
503`K9O_ENVELOPE_KEK_UNAVAILABLE`: the KEK couldn't be reached. Retry later.
Response body (200)
keyId *string

The KEK that was rotated (vkey_*).

Example: "vkey_7Rt2Wq9LxP4m"
newVersion *integer <int64>

The KEK version active now.

Example: 4
previousVersion *integer <int64>

The KEK version active before the re-key.

Example: 3
status *string

Always rotated: the re-wrap window closed and the flip committed.

Example: "rotated"
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.keys.rotate('<keyId>')

Showing example in TypeScript

Response example (200)
{
  "keyId": "vkey_7Rt2Wq9LxP4m",
  "newVersion": 4,
  "previousVersion": 3,
  "status": "rotated"
}

More in Keys