Skip to main content
POST
Create institution config and provision keys

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), admission sets (blockableBalances/blockableAccountTypes), and the connector's credentials under their snake_case allowlisted names (ledger_client_id, ledger_client_secret, crm_client_id, crm_client_secret). 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. Credential values are sealed before the row is written and are never echoed.

Example:
retryPolicyConfig
any

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

Example:

Response

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, 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:
retryPolicyConfig
any

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

Example: