Rotate an institution's KEK

Triggers a manual key-encryption-key rotation for the addressed institution. The KEK advances and the registry mirror syncs; the per-record DEKs are rewrapped asynchronously by the backfill (rewrapStatus IN_PROGRESS), and audit_event DEKs are never rewrapped. An institution with no provisioned (ACTIVE registered) key maps to 404 (SBJ-0005) before any KMS call, with either KMS_PROVIDER. A key registry whose ACTIVE version is behind the KMS’s live version maps to 409 SBJ-0012 before any KMS call (restart the service to reconcile, then retry); one ahead of it maps to 409 SBJ-0012 (not retryable). The live version read made before any KMS call also maps to 409 SBJ-0012 (not retryable; nothing is rotated or written), with either KMS_PROVIDER, when the registered key is no longer in the KMS (vault: the Transit key is missing; aws: the alias or the key is gone), when the KMS denies access to the key (aws AccessDenied, on the key or on its key-material listing), when the key is disabled or not in a usable state, or when the recorded key version is not readable. 409 SBJ-0007 means only a contended same-institution rotation (retryable once it completes). 409 SBJ-0012 (not retryable) covers, with KMS_PROVIDER=aws managed, a registered reference that cannot be verified (legacy alias label, bare multi-Region id or malformed; refused before any KMS call), a key behind the alias that differs from the registered key, or a registered key no longer reachable under its alias (all not retryable; nothing is rotated or written). A definitive KMS refusal of the rotation request also maps to 409 (SBJ-0012, not retryable, nothing rotated): with aws managed access denied, key not found, key disabled or not in a rotatable state, or the key’s on-demand rotation quota exhausted; with vault any 4xx answer to the Transit rotate write other than 429. A transient KMS failure before any rotation maps to 503 (SBJ-0008, retryable): with aws throttling of the single rotation request attempt (the SDK does not retry it); with vault a 429 on the Transit rotate write or a transient failure before it. A rotation whose outcome is unknown maps to 500 SBJ-0013 (rotation outcome unknown; do not retry; the key registry reconciles on service restart): an uncertain failure of the rotation request (aws: timeout, server fault, conflict, transport; vault: a 5xx, 408, transport error or timeout on the Transit rotate write) whose KMS advance is not proven by the live version read that follows it. A KEK owned by the key custodian (KMS_PROVIDER=aws with KMS_AWS_KEY_MODE=provided) is never rotated by the service and maps to 422 with nothing changed (no lock, no audit, no KMS call); a rotation the KMS is proven to have made (the rotation request completed, or the live version read after an uncertain one shows the key advanced) whose follow-up was refused or failed (registry advance or audit) maps to 500 SBJ-0014 (do not retry), whatever the cause. Every other 500 is SBJ-0002. Every 5xx body is the generic “internal error”; the code is the client’s branch.

POST /v1/institutions/{institutionId}/security/kek:rotate

Rotate an institution's KEK

cURL

curl --request POST \
  --url https://api.example.com/v1/institutions/{institutionId}/security/kek:rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "scheduled_annual_rotation"
}
'

200

{
  "institutionId": "44444444-4444-4444-4444-444444444444",
  "newKekVersion": "v3",
  "previousKekVersion": "v2",
  "rewrapStatus": "IN_PROGRESS",
  "rotatedAt": "2026-06-08T12:00:00Z"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Path Parameters

institutionId · string · required

The institution's unique identifier (UUID) the KEK rotation targets.

Example:

"44444444-4444-4444-4444-444444444444"

Body

application/json

reason · string

Optional operator-supplied free-text reason for the rotation (sealed verbatim into the audit payload).

Example:

"scheduled_annual_rotation"

Response

200

application/json

OK

institutionId · string · required

The institution the rotation targeted.

Example:

"44444444-4444-4444-4444-444444444444"

newKekVersion · string · required

The newly active KEK version.

Example:

"v3"

previousKekVersion · string · required

The KEK version that was active before the rotation.

Example:

"v2"

rewrapStatus · string · required

The rewrap progress status (e.g. IN_PROGRESS).

Example:

"IN_PROGRESS"

rotatedAt · string · required

The RFC3339 timestamp the rotation committed.

Example:

"2026-06-08T12:00:00Z"