POST
/vault/keys/{key_id}/rotateRotate 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
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | The key was rotated: every data key is wrapped under the new version. | |
| 401 | The request carries no authenticated caller. | |
| 403 | The 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 ( 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 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"
}