Rotate an institution's connector-credentials KEK

Rotates the key that wraps this institution’s stored connector credentials — a DIFFERENT key from the institution-data KEK governing PII, whose rotation is owned by the Lerian SISBAJUD Mensageria. The Transit key advances and the stored credentials envelope is rebound to the new version; no credential is decrypted and no credential VALUE changes, so a leaked client_secret is NOT invalidated by this call (rotate the material itself with PUT /v1/institutions//connector-credentials, and revoke it upstream). rewrapStatus reports whether the stored envelope was rebound or the row carried no sealed subtree to rebind. An institution that has never stored a connector credential has no credentials KEK and maps to 404, not to a rotation. Code SBJ-0007 is a 409 a retry resolves: a contended same-institution rotation (retry once it completes) or a key registry this request reconciled or that changed while it was being reconciled (below); every other 409 below carries code SBJ-0012 (rotation not retryable; see detail). Any failure after the key rotated (reading the new version, recording it in the key registry, loading the configuration, rewrapping or persisting the envelope, including a concurrent change to this institution’s connector configuration that wins the envelope write; the envelope still decrypts under the previous version) maps to 500 with code SBJ-0014 (rotation committed but a follow-up step failed; do not retry). Before the rotation, an ACTIVE key-registry version behind the key service’s is reconciled by the request itself (recorded with a SYSTEM audit event) and the call maps to 409 (SBJ-0007) with nothing rotated: retry (if the registry or the live key version changed during that reconciliation, also 409 SBJ-0007: retry); a version ahead of the key service’s, or one that is not readable, maps to 409 (SBJ-0012) with nothing rotated: do not retry. With KMS_AWS_KEY_MODE=managed, a key alias that no longer resolves to the key the registry records also maps to 409 (not retryable): nothing is rotated or written. So does a rewrap whose key is not the one the key registry records (the alias resolves to another key, or the registry records no ACTIVE key); a key registry that cannot be read before any key is used maps to 503 (retryable). A recorded key reference that cannot be verified (a legacy label or an unknown format) also maps to 409, before any key-service call; so does a definitive key-service refusal (access denied, a disabled key, a key state that does not allow rotation, or the key’s exhausted on-demand rotation quota), naming the reason. A key-service throttle or outage before the rotation request was sent maps to 503 (retryable); a failure once the rotation request may have reached the key service (a timeout, a 5xx, a conflict, a dropped connection) maps to 500 with code SBJ-0013 (rotation outcome unknown; do not retry; the next rotation request reconciles the key registry). An unknown institution maps to 404. A committed-but-unaudited rotation maps to 500 with code SBJ-0014 (non-retryable; escalate). Every 500 body is the scrubbed internal error: the code carries the meaning. With KMS_PROVIDER=aws and KMS_AWS_KEY_MODE=provided the key is customer-provided and its rotation is owned by the key custodian: the call maps to 422 (SBJ-0006) and changes nothing — no lock, no audit, no KMS call. That refusal precedes any institution lookup, so in that mode an unknown institution, or one without a credentials KEK, also gets 422 rather than 404. A body of 1 MiB (1,048,576 bytes, the operation’s body limit) or more maps to 413 as application/problem+json (SBJ-0010); only a body over HTTP_BODY_LIMIT_BYTES (100 MiB by default) is refused earlier by the server’s body limit, as a 413 application/json ErrorResponse, so both media types are declared for 413. 401 and 403 come from the /v1 auth chain and 429 from the rate limiter (SBJ-0009), each as an application/json ErrorResponse; that chain can also answer 500 or 503 (for example when the authorization or tenant backend is unavailable) in the same ErrorResponse shape, while the 500 and 503 documented below are the handler’s application/problem+json responses.

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

Rotate an institution's connector-credentials KEK

cURL

curl --request POST \
  --url https://api.example.com/v1/institutions/{institutionId}/security/credential-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) whose connector-credentials KEK is rotated.

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"