> ## 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 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/{institutionId}/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. ## OpenAPI ````yaml /en/openapi/v3-current/sisbajud-executor.yaml post /v1/institutions/{institutionId}/security/credential-kek:rotate openapi: 3.1.0 info: description: >- API for the Lerian SISBAJUD executor, which runs judicial orders on Midaz. It covers institution and Midaz connector configuration, orders that need attention, ledger-routing checks, credential key rotation and audit verification. title: Lerian SISBAJUD Executor 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 a connector configuration addressed by institution id. name: Institution - description: >- Rotation of the key that wraps an institution's stored connector credentials, addressed by institution id. name: Security - description: 'Admin API: audit-trail integrity verification.' name: Admin paths: /v1/institutions/{institutionId}/security/credential-kek:rotate: post: tags: - Security summary: Rotate an institution's connector-credentials KEK description: >- 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/{institutionId}/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. operationId: rotate-institution-credentials-kek parameters: - description: >- The institution's unique identifier (UUID) whose connector-credentials KEK is rotated. in: path name: institutionId required: true schema: description: >- The institution's unique identifier (UUID) whose connector-credentials KEK is rotated. 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 '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Forbidden '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Conflict '413': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Request Entity Too Large '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Too Many Requests '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Service Unavailable 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 ErrorResponse: additionalProperties: false properties: code: type: string details: additionalProperties: {} type: object message: type: string title: type: string required: - code - title - message 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.