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. With KMS_PROVIDER=aws managed, a key the institution alias names that is not yet registered (another provisioning holds it) maps to 503 SBJ-0008 (retryable), and one that is not the registered key maps to 409 SBJ-0012 (not retryable; nothing is adopted).

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 '
{
  "enabled": true,
  "institutionCode": "12345678",
  "institutionId": "550e8400-e29b-41d4-a716-446655440000",
  "retryPolicyConfig": {
    "initialBackoffMs": 100,
    "maxAttempts": 3
  }
}
'

201

{
  "createdAt": "2024-01-15T10:30:00Z",
  "enabled": true,
  "institutionCode": "12345678",
  "institutionId": "550e8400-e29b-41d4-a716-446655440000",
  "updatedAt": "2024-01-15T12:00:00Z",
  "retryPolicyConfig": {
    "maxAttempts": 3
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

enabled · boolean · required

Whether the institution 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"

retryPolicyConfig · any

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

Example:

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

Response

201

application/json

Created

createdAt · string · required

RFC 3339 creation timestamp (UTC).

Example:

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

enabled · boolean · required

Whether the institution 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"

retryPolicyConfig · any

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

Example:

{ "maxAttempts": 3 }