Update institution config by id

Applies a partial update (connectorType/institutionCode/retryPolicyConfig/connectorMetadata/enabled/credentials) to an existing institution configuration addressed by the path id. connectorMetadata, when present, replaces the entire bag wholesale. credentials, when present, rotates the institution’s connector credentials. Returns 404 when the institution has no configuration.

PATCH /institutions/{institutionId}

Update institution config by id

cURL

curl --request PATCH \
  --url https://sisbajud.sandbox.lerian.net/institutions/{institutionId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connectorMetadata": {
    "authAddress": "https://auth.example.com",
    "baseUrl": "https://midaz.example.com",
    "blockableAccountTypes": [
      "deposit"
    ],
    "blockableBalances": [
      "default"
    ],
    "credentials": {
      "crm_client_id": "midaz-crm-client",
      "crm_client_secret": "REPLACE_ME",
      "ledger_client_id": "midaz-ledger-client",
      "ledger_client_secret": "REPLACE_ME"
    },
    "crmBaseUrl": "https://midaz-crm.example.com",
    "crmMode": "legacy",
    "organizations": [
      {
        "ledgers": [
          "019fcd7c-1e18-7034-8cd3-9e39c1759e41"
        ],
        "organizationId": "019fcd7b-97df-71a5-8023-6eb3c661968b"
      }
    ]
  },
  "connectorType": "midaz",
  "enabled": false,
  "institutionCode": "12345678",
  "retryPolicyConfig": {
    "maxAttempts": 5
  }
}
'

200

{
  "connectorType": "midaz",
  "createdAt": "2024-01-15T10:30:00Z",
  "enabled": true,
  "institutionCode": "12345678",
  "institutionId": "550e8400-e29b-41d4-a716-446655440000",
  "updatedAt": "2024-01-15T12:00:00Z",
  "connectorMetadata": {
    "baseUrl": "https://midaz.example.com",
    "blockableAccountTypes": [
      "deposit"
    ],
    "blockableBalances": [
      "default"
    ],
    "organizations": [
      {
        "ledgers": [
          "019fcd7c-1e18-7034-8cd3-9e39c1759e41"
        ],
        "organizationId": "019fcd7b-97df-71a5-8023-6eb3c661968b"
      }
    ]
  },
  "connectorMetadataValid": false,
  "effectiveCrmMode": "legacy",
  "retryPolicyConfig": {
    "maxAttempts": 3
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Path Parameters

institutionId · string · required

The institution's unique identifier (UUID).

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

connectorMetadata · any

Connector-specific configuration bag. When present, replaces the entire bag wholesale, with ONLY the connector-owned credentials subtree carried over when omitted. baseUrl, organizations[] and authAddress are NOT carried over, so a replacing bag must re-supply baseUrl and organizations[] (both always required) and authAddress (required whenever credentials remain, supplied or carried), or the write is rejected. A credentials subtree in the patched bag ROTATES the stored credentials: it is sealed under a fresh data key in this same write, and this is the only credential-rotation path (there is no separate endpoint). Rotating here does NOT revoke the previous credential upstream and does not take effect on other replicas until their connector cache expires, so rotating a LEAKED credential also requires revoking it at the identity provider. Omitting credentials leaves the stored ones untouched; credentials cannot be removed by PATCH (an empty or partial subtree is rejected). There is no authMode; a rotation supplies the complete set for the effective crmMode: ledger_client_id + ledger_client_secret always, plus crm_client_id + crm_client_secret when legacy (required) — never under embedded (forbidden). Switching legacy→embedded while omitting credentials carries the stored crm_* pair over and is rejected, so that switch must supply a ledger-only credentials subtree. crmMode is part of the replaced bag like any other key: a patched bag that omits it drops the override and the institution falls back to inheriting MIDAZ_CRM_MODE. Omit this field entirely to leave the stored bag untouched — an explicitly supplied null decodes to the same absent pointer and is likewise a no-op on this column, not a request to clear it (true of every field of this body, since they are all pointers).

Example:

{
  "authAddress": "https://auth.example.com",
  "baseUrl": "https://midaz.example.com",
  "blockableAccountTypes": ["deposit"],
  "blockableBalances": ["default"],
  "credentials": {
    "crm_client_id": "midaz-crm-client",
    "crm_client_secret": "REPLACE_ME",
    "ledger_client_id": "midaz-ledger-client",
    "ledger_client_secret": "REPLACE_ME"
  },
  "crmBaseUrl": "https://midaz-crm.example.com",
  "crmMode": "legacy",
  "organizations": [
    {
      "ledgers": ["019fcd7c-1e18-7034-8cd3-9e39c1759e41"],
      "organizationId": "019fcd7b-97df-71a5-8023-6eb3c661968b"
    }
  ]
}

connectorType · string

The outbound connector type. Omitted fields are left unchanged.

Example:

"midaz"

enabled · boolean

Whether the connector configuration is active. Omitted leaves the flag unchanged; explicitly false disables it.

Example:

false

institutionCode · string

The institution's BACEN CNPJ (8 digits). When present, replaces the stored value.

Example:

"12345678"

retryPolicyConfig · any

Operational retry policy as arbitrary JSON. When present, replaces the stored value.

Example:

{ "maxAttempts": 5 }

Response

200

application/json

OK

connectorType · string · required

The outbound connector type for this institution.

Example:

"midaz"

createdAt · string · required

RFC 3339 creation timestamp (UTC).

Example:

"2024-01-15T10:30:00Z"

enabled · boolean · required

Whether the connector configuration is active.

Example:

true

institutionCode · string · required

The institution's BACEN CNPJ (8 digits) for return-file headers and file header validation.

Example:

"12345678"

institutionId · string · required

The institution's unique identifier (UUID).

Example:

"550e8400-e29b-41d4-a716-446655440000"

updatedAt · string · required

RFC 3339 last-update timestamp (UTC).

Example:

"2024-01-15T12:00:00Z"

connectorMetadata · any

Connector-specific configuration bag. The non-secret connector-owned keys (baseUrl, authAddress, crmBaseUrl, crmMode, organizations[], blockableBalances, blockableAccountTypes, salaryAccountTypes) are preserved verbatim; secret-bearing keys — the whole credentials subtree included — are removed and never echoed. blockableBalances carries the LEDGER's balance-key values — for Midaz, balanceKey (default/overdraft/a client-registered key), not the available/onHold fields of a balance.

Example:

{
  "baseUrl": "https://midaz.example.com",
  "blockableAccountTypes": ["deposit"],
  "blockableBalances": ["default"],
  "organizations": [
    {
      "ledgers": ["019fcd7c-1e18-7034-8cd3-9e39c1759e41"],
      "organizationId": "019fcd7b-97df-71a5-8023-6eb3c661968b"
    }
  ]
}

connectorMetadataValid · boolean · read-only

Present and false only when the stored connector metadata cannot be parsed by its connector; absent otherwise. The offending value is never echoed.

Example:

false

effectiveCrmMode · enum<string> · read-only

The CRM surface this institution resolves to (legacy|embedded): its own crmMode override when the connector metadata names one, the service-wide default otherwise. Derived and read-only; omitted when the connector metadata cannot be parsed.

Available options: legacy, embedded

Example:

"legacy"

retryPolicyConfig · any

Operational retry policy (backoff/attempts) as arbitrary JSON.

Example:

{ "maxAttempts": 3 }