> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /es/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/security/kek:rotate openapi: 3.1.0 info: description: >- API for the Lerian SISBAJUD Mensageria, the regulatory side of Lerian SISBAJUD. It covers institution configuration, order and file queries, return files, LGPD requests, key rotation, non-compliance justifications and the Lerian STA dead-letter queue. title: Lerian SISBAJUD Mensageria API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: >- Institution configuration lifecycle: create (with key provisioning), read, and partial update of an institution configuration addressed by institution id. name: Institution - description: >- LGPD data-subject access, portability and resolution operations, addressed by institution id. name: LGPD - description: >- Manual cryptographic key administration: KEK and tokenization-keyset rotation for an institution, addressed by institution id. name: Security - description: >- Non-compliance-log administration, such as registering an SLA-breach justification, addressed by institution id. name: Non-Compliance - description: >- Return (response) file administration, such as forcing an on-demand return-file generation outside the scheduled cron. name: Return File - description: >- Admin read API: institution-scoped order, file, SLA, and processing-stats queries, plus audit-trail integrity verification. PII fields are masked unless the caller proves a cleartext grant. name: Admin paths: /v1/institutions/{institutionId}/security/kek:rotate: post: tags: - Security summary: Rotate an institution's KEK description: >- 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. operationId: rotate-institution-kek parameters: - description: The institution's unique identifier (UUID) the KEK rotation targets. in: path name: institutionId required: true schema: description: >- The institution's unique identifier (UUID) the KEK rotation targets. examples: - 44444444-4444-4444-4444-444444444444 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RotateKEKRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/RotateInstitutionKekResponse' description: OK '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- SBJ-0005: the institution has no provisioned key (either KMS_PROVIDER); nothing was rotated. '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- SBJ-0007: a rotation already in progress (retryable). SBJ-0012: the key registry is behind the key custodian (restart the service to reconcile, then retry) or ahead of it (not retryable), both before any KMS call; on the live version read before any KMS call (not retryable) a registered key no longer in the KMS, an access denial (aws), a disabled key or a recorded key version that is not readable; (KMS_PROVIDER=aws managed, not retryable) a registered reference that cannot be verified, a key behind the alias that differs from the registered key or one no longer reachable under it; or a definitive KMS refusal of the rotation request (aws: access denied, not found, disabled, rotation quota exhausted; vault: a 4xx other than 429 on the Transit rotate write); not retryable. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- SBJ-0013: rotation outcome unknown; do not retry; the key registry reconciles on service restart. SBJ-0014: rotation committed but a follow-up step failed; do not retry. SBJ-0002: any other internal error. The body detail is always "internal error". '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- A transient KMS failure before any rotation (aws: throttling of the single rotation request attempt; vault: a 429 on the Transit rotate write, or a transient failure before it); retryable. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: RotateKEKRequest: additionalProperties: false properties: reason: description: >- Optional operator-supplied free-text reason for the rotation (sealed verbatim into the audit payload). examples: - scheduled_annual_rotation type: string type: object RotateInstitutionKekResponse: additionalProperties: false properties: institutionId: description: The institution the rotation targeted. examples: - 44444444-4444-4444-4444-444444444444 type: string newKekVersion: description: The newly active KEK version. examples: - v3 type: string previousKekVersion: description: The KEK version that was active before the rotation. examples: - v2 type: string rewrapStatus: description: The rewrap progress status (e.g. IN_PROGRESS). examples: - IN_PROGRESS type: string rotatedAt: description: The RFC3339 timestamp the rotation committed. examples: - '2026-06-08T12:00:00Z' type: string required: - institutionId - newKekVersion - previousKekVersion - rotatedAt - rewrapStatus type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.