Cumbuca Gateway API Quickstart

Reference for the Cumbuca Open Finance data-sharing API: participant directory, data-sharing consent lifecycle, Phase 2 data consumption endpoints, and the shared consent management portal.

Background - Open Finance Brasil

This section is a high-level primer for readers new to the ecosystem. If you already know how Open Finance Brasil works, jump straight to Overview.

What is Open Finance Brasil

Open Finance Brasil is a Central Bank-regulated programme that lets customers (individuals and legal entities) share their financial data across institutions in a standardised, secure way. The same idea that powered Pix's interoperability is applied to the rest of the financial stack: accounts, cards, credit, investments, and FX.

The Central Bank (BACEN) sets the rules and publishes the regulated APIs; a Deliberative Council coordinated by an industry-wide governance structure operationalises them through working groups (security, customer experience, infrastructure, etc.). Compliance is not optional: every regulated institution must expose the standard APIs in the way the spec defines.

Participation roles

Each institution joins the ecosystem under one or more roles. For data sharing, the roles split into a passive side (holds the data) and an active side (asks for the data):

An institution can hold multiple roles simultaneously (data and payments). For this data-sharing reference, the relevant tag in the participants directory is DADOS; that's what you'll see filtered in GET /consent-management/v1/participants.

Client vs server in the protocol. The passive/active split lines up directly with the OAuth client/server split. The Receptor de Dados plays the role of OAuth client: it registers via DCR, asks for authorisation, holds the access token, and makes the API calls. The Transmissor de Dados plays the role of Authorisation Server (AS) and resource server: it authenticates the user, issues consents and tokens, and serves the regulated endpoints. So when you read "AS" in the FAPI-BR spec, picture the bank that holds the customer's data; when you read "client", picture the fintech driving the integration.

Implementation phases

The programme rolled out in four phases. The labels are still used everywhere in the spec and in conversations:

• Phase 1 (Open Data). Public, no-consent-needed information about institutions, products, rates, branches.
• Phase 2 (Customer Data). Consented sharing of customer-owned data: accounts, cards, credit operations, investments, FX. Most of the GETs you'll find under Data Consumption live here.
• Phase 3 (Services). Payment initiation and credit portability (out of scope for this reference).
• Phase 4 (Extensions). Continuous refinements to the earlier phases.

How institutions communicate

Two cross-cutting standards govern every request between institutions:

• mTLS (mutual TLS). Both sides present X.509 certificates issued by approved CAs (CertiSign, Serpro, Soluti). The TLS handshake itself is the first layer of authentication: an institution that isn't in the directory can't even open a connection.
• Message signing (JWS). Sensitive request and response bodies (such as recurring consent retrieval) are wrapped in a compact JWS: the body is a base64url header.payload.signature string, signed with a separate signing certificate. This guarantees integrity end-to-end, even when the message passes through proxies.

These two combined implement the FAPI-BR security profile, a Brazilian regional flavour of OpenID Foundation's Financial-grade API standard. On top of FAPI-BR, the standard OAuth 2.0 / OIDC building blocks are used:

• DCR (Dynamic Client Registration): institutions register their OAuth clients programmatically.
• PAR (Pushed Authorisation Request): the authorisation request is pre-registered on the holder side, so the redirect URL the user sees is short, signed, and tamper-proof.
• OIDC redirect flow: the user is sent to the holder's bank, authenticates, authorises, and is redirected back to the initiator's callbackApplicationUri.

For first-time integrations all of this orchestration (directory lookup, DCR, token exchange, PAR, mTLS handshake) happens for every call. It's a lot of moving parts.

Simplified request flow, putting the pieces together for a typical authorised data read:

Every arrow between client and AS rides on mTLS. Steps that expose private data (steps 2 and 5/6) additionally carry JWS-signed payloads. The customer's browser is only involved on steps 3 and 4: the redirect handoff that triggers authentication and brings the user back.

Consent at the centre

Every cross-institution data read is anchored on a consent. The consent is a regulated artefact created on the holder side and tied to:

• The customer's identification document (CPF or CNPJ).
• The permissions being authorised.
• An expiration window.
• The active institution (the data receiver) that asked for it.

Until the consent is in AUTHORISED state, no protected resource can be read. After it expires, the holder will refuse the call. Picking up consent state and reacting to it (see GET /consent-management/v1/consents/{consentId}) is therefore central to any integration.

Where Cumbuca fits in

Cumbuca acts as the regulatory plumbing for institutions that want to participate as data receivers without having to build the full FAPI-BR stack in-house. The two-prefix structure you'll see throughout this reference reflects that:

• /consent-management/...: Cumbuca's orchestration layer. A single HTTP call internally chains DCR → token → consent creation → PAR → redirect URL, so the integrator only deals with one request per business operation.
• /open-finance/...: transparent proxy to the regulated APIs. mTLS and JWS verification of responses happen inside the proxy.

The rest of this document is the API reference for those two layers.

{
  "errors": [
    {
      "code": "INVALID_REQUEST",
      "title": "Validation failed",
      "detail": "data.payment.amount must be a string"
    }
  ]
}

Authentication

All endpoints in this reference (except the one below) require an Authorization: Bearer <access_token> header. Access tokens are short-lived; long-lived refresh tokens let the client renew them without re-exchanging credentials.

POST /auth/v1/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOi...",
  "refresh_expires_in": 2592000
}

Directory

[
  {
    "CustomerFriendlyName": "Banco X",
    "CustomerFriendlyLogoUri": "https://...",
    "AuthorisationServerIds": ["asid-uuid"],
    "OrgDomainRoleClaims": [
      { "Role": "DADOS", "Status": "Active" },
      { "Role": "CONTA", "Status": "Active" }
    ],
    "ApiResources": [{ "ApiFamilyType": "accounts" }],
    "Organisations": [{ "RegisteredName": "BANCO X S.A." }]
  }
]

{
  "data": "code=LxSev...&id_token=eyJ...&state=dXJu..."
}

{
  "error": "authorization_failed",
  "error_description": "authorization could not be completed"
}

Data Sharing Consent

{
  "data": {
    "callbackApplicationUri": "https://.../consent/callback",
    "loggedUser": {
      "document": { "identification": "12345678901", "rel": "CPF" }
    },
    "businessEntity": { // optional - when the logged user acts as a legal-entity representative
      "document": { "identification": "12345678000199", "rel": "CNPJ" }
    },
    "permissions": [
      "ACCOUNTS_READ", "ACCOUNTS_BALANCES_READ",
      "RESOURCES_READ"
    ],
    "expirationDateTime": "2026-05-28T15:10:00Z"
  }
}

{
  "data": {
    "consentId": "urn:cumbuca:C123ABC...",
    "redirectUrl": "https://auth.bank.example/oauth2/authorize?..."
  }
}

{
  "data": {
    "consentId": "urn:raidiambank:c4bb1a06-8dcf-4935-9696-b40bf6911f50",
    "consent": {
      "data": {
        "consentId": "urn:raidiambank:c4bb1a06-...",
        "status": "AUTHORISED",
        "creationDateTime": "2026-01-29T16:34:29Z",
        "statusUpdateDateTime": "2026-01-29T16:34:41Z",
        "expirationDateTime": "2026-07-29T16:34:27Z",
        "permissions": ["ACCOUNTS_READ", "ACCOUNTS_BALANCES_READ", "RESOURCES_READ"]
      },
      "links": { "self": "https://matls-api.<bank>/open-finance/consents/v3/consents/<consentId>" },
      "meta": { "requestDateTime": "2026-01-29T16:35:00Z" }
    }
  }
}

Consent lifecycle. Beyond creation and lookup, three lifecycle operations are available: DELETE /consent-management/v1/consents/{consentId} revokes the consent (returns 204); POST .../consents/{consentId}/authorisation-retry mints a fresh redirectUrl when the original authorisation attempt lapsed (e.g. the user abandoned the bank redirect); and POST .../consents/{consentId}/extends renews an AUTHORISED consent's expiration. This POST alone additionally requires the x-customer-user-agent and x-fapi-customer-ip-address headers, and a companion GET on the same path lists the extension history.

Data Consumption (Phase 2) - Authenticated GETs

All endpoints in this section follow the same shape:

• Method: GET
• Headers: Authorization: Bearer <access_token>, x-authorisation-server-id, x-consent-id
• Response: { "data": [...] } (regulated OF Brasil format)
• Retries: data reads are billable; see Rate limits and Timeouts & retries before adding retry logic.

Customers

Accounts (Checking / Savings)

Credit Cards

Credit Operations (4 families)

Generic shape for the scopes loans, financings, invoice-financings, and unarranged-accounts-overdraft:

Investments (5 families)

Scopes: bank-fixed-incomes, credit-fixed-incomes, variable-incomes, treasure-titles, funds.

Exchanges (FX)

Resources (discovery)

Reciprocity

As a data receiver you are also expected to make your own account holders' registration data available to the ecosystem (reciprocidade). The write below populates the reciprocity store Cumbuca serves on your behalf: once a customer is registered, other Open Finance participants querying your institution get a positive account-holder check and the registered identification data.

{
  "data": { "cpf": "12345678901" }
}

Consent Management

Lets the end user view, manage, and revoke all the consents they've authorised for the client. The call returns a one-time URL; redirect the user there to open the management portal. See also Reciprocity for the register write that keeps your own account holders' data available to the ecosystem.

{
  "document": "12345678901",
  "representativeCpf": "98765432100"
}

{
  "redirectUrl": "https://.../management/?token=..."
}

Appendix

Permissions mapping

Open Finance Brasil groups permissions by data category and grouping (the granular sharing unit the user authorises). Each grouping maps to a set of regulated permission strings. RESOURCES_READ must always be included when creating a data-sharing consent.

Cumbuca Gateway API - Data Sharing.