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. Invalid input is refused with 400 SBJ-0001, including an empty or malformed institutionCode and a branchFormat/accountFormat that does not compile or is longer than 64 characters. A key that is not the one the key registry records (the institution’s key alias resolves to another key, or the registry records no ACTIVE key) maps to 409 SBJ-0012 and changes nothing: do not retry. A key being provisioned by another request, or a key registry that cannot be read, maps to 503 (retryable). 401 and 403 come from the /v1 auth chain and 429 from the rate limiter, as an application/json ErrorResponse.

POST /v1/institutions

Create institution config and provision keys

cURL

curl --request POST \
  --url https://api.example.com/v1/institutions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connectorType": "midaz",
  "enabled": true,
  "institutionCode": "12345678",
  "institutionId": "550e8400-e29b-41d4-a716-446655440000",
  "accountFormat": "^[0-9]{1,12}$",
  "branchFormat": "^[0-9]{4}$",
  "connectorMetadata": {
    "blockableAccountTypes": [
      "deposit"
    ],
    "blockableBalances": [
      "default"
    ],
    "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",
  "accountFormat": "^[0-9]{1,12}$",
  "branchFormat": "^[0-9]{4}$",
  "connectionSource": "env",
  "connectorMetadata": {
    "blockableAccountTypes": [
      "deposit"
    ],
    "blockableBalances": [
      "default"
    ],
    "organizations": [
      {
        "ledgers": [
          "019fcd7c-1e18-7034-8cd3-9e39c1759e41"
        ],
        "organizationId": "019fcd7b-97df-71a5-8023-6eb3c661968b"
      }
    ]
  },
  "connectorMetadataValid": false,
  "effectiveCrmMode": "legacy",
  "retryPolicyConfig": {
    "maxAttempts": 3
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Cuerpo

application/json

connectorType · string · requerido

The outbound connector type for this institution.

Ejemplo:

"midaz"

enabled · boolean · requerido

Whether the connector configuration is active.

Ejemplo:

true

institutionCode · string · requerido

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

Ejemplo:

"12345678"

institutionId · string · requerido

The institution's unique identifier (UUID) that addresses the new configuration.

Ejemplo:

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

accountFormat · string

Regular expression (Go RE2 syntax, at most 64 characters) the institution DECLARES for the account number a court may indicate in a BLOQUEIO restriction. A value is proven invalid (TARGET_INVALID) only when it fails the WHOLE pattern; with no declaration nothing is ever proven invalid. Per institution and never defaulted. A pattern that does not compile, or is longer than 64 characters, is refused with 400. Absent or blank declares nothing.

Ejemplo:

"^[0-9]{1,12}$"

branchFormat · string

Regular expression (Go RE2 syntax, at most 64 characters) the institution DECLARES for the branch (agência) number a court may indicate in a BLOQUEIO restriction. A value is proven invalid (TARGET_INVALID) only when it fails the WHOLE pattern; with no declaration nothing is ever proven invalid. Per institution and never defaulted. A pattern that does not compile, or is longer than 64 characters, is refused with 400. Absent or blank declares nothing.

Ejemplo:

"^[0-9]{4}$"

connectorMetadata · any

Connector-specific configuration bag: routing (organizations[] required — the only targeting form, at least one entry naming a Midaz organizationId with optional ledgers; crmMode optional — legacy|embedded, where absent/null/blank INHERITS the service-wide MIDAZ_CRM_MODE and an unrecognised value is rejected) and admission sets (blockableBalances/blockableAccountTypes). The Midaz connection (base URL, auth address, credentials) comes from the MIDAZ_* environment of the installation: baseUrl, authAddress and crmBaseUrl are dropped, and a credentials subtree that holds values is refused with 400. 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. 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.

Ejemplo:

{
  "blockableAccountTypes": ["deposit"],
  "blockableBalances": ["default"],
  "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.

Ejemplo:

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

Respuesta

201

application/json

Created

connectorType · string · requerido

The outbound connector type for this institution.

Ejemplo:

"midaz"

createdAt · string · requerido

RFC 3339 creation timestamp (UTC).

Ejemplo:

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

enabled · boolean · requerido

Whether the connector configuration is active.

Ejemplo:

true

institutionCode · string · requerido

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

Ejemplo:

"12345678"

institutionId · string · requerido

The institution's unique identifier (UUID).

Ejemplo:

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

updatedAt · string · requerido

RFC 3339 last-update timestamp (UTC).

Ejemplo:

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

accountFormat · string

The regular expression the institution declared for the account number of a court-indicated target; omitted when none is declared.

Ejemplo:

"^[0-9]{1,12}$"

branchFormat · string

The regular expression the institution declared for the branch (agência) number of a court-indicated target; omitted when none is declared.

Ejemplo:

"^[0-9]{4}$"

connectionSource · enum<string> · read-only

Where the Midaz connection comes from: env, the MIDAZ_* environment of the installation. Derived and read-only.

Opciones disponibles: env

Ejemplo:

"env"

connectorMetadata · any

Connector-specific configuration bag. The non-secret connector-owned keys (crmMode, organizations[], blockableBalances, blockableAccountTypes, salaryAccountTypes) are preserved verbatim. 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.

Ejemplo:

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

Ejemplo:

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.

Opciones disponibles: legacy, embedded

Ejemplo:

"legacy"

retryPolicyConfig · any

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

Ejemplo:

{ "maxAttempts": 3 }