Create institution config and provision keys

Creates a new institution configuration (create-only; 409 if one already exists for the id) and provisions its tokenization PRF + audit MAC keysets in the same flow. The institution id is supplied in the request body.

POST /institutions

Create institution config and provision keys

cURL

curl --request POST \
  --url https://sisbajud.sandbox.lerian.net/institutions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connectorType": "midaz",
  "enabled": true,
  "institutionCode": "12345678",
  "institutionId": "550e8400-e29b-41d4-a716-446655440000",
  "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"
      }
    ]
  },
  "retryPolicyConfig": {
    "initialBackoffMs": 100,
    "maxAttempts": 3
  }
}
'

201

{
  "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.

Body

application/json

connectorType · string · required

The outbound connector type for this institution.

Example:

"midaz"

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) that addresses the new configuration.

Example:

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

connectorMetadata · any

Connector-specific configuration bag: routing (baseUrl required; organizations[] required — the only targeting form, at least one entry naming a Midaz organizationId with optional ledgers; authAddress required when credentials are present; crmBaseUrl optional; crmMode optional — legacy|embedded, where absent/null/blank INHERITS the service-wide MIDAZ_CRM_MODE, an unrecognised value is rejected, and embedded requires an EMPTY crmBaseUrl), admission sets (blockableBalances/blockableAccountTypes), and the connector's credentials under their snake_case allowlisted names: ledger_client_id + ledger_client_secret are always required when credentials are present; crm_client_id + crm_client_secret are an all-or-nothing pair that is REQUIRED when the effective crmMode is legacy and FORBIDDEN when it is embedded (an embedded bag carries the ledger pair only, e.g. credentials:{ledger_client_id,ledger_client_secret}); the example shows the legacy four-field shape. blockableBalances carries the LEDGER's balance-key values (for Midaz: balanceKey, e.g. default/overdraft/a client-registered key) — NOT available/onHold, which are fields of a balance, not keys; the set is open and unvalidated, so a wrong value is not rejected, it only makes the admission gate never match. The presence of the credentials subtree selects authentication; there is no authMode. crmMode is a cleartext routing selector, never a credential: it is preserved on GET, which also echoes the RESOLVED surface as the read-only effectiveCrmMode. Credential values are sealed before the row is written and are never echoed.

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"
    }
  ]
}

retryPolicyConfig · any

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

Example:

{ "initialBackoffMs": 100, "maxAttempts": 3 }

Response

201

application/json

Created

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 }