Securing Your Bradesco API Integration: OAuth 2.0 and mTLS

When integrating with Bradesco's financial APIs, security is non-negotiable. The APIs handle sensitive financial data and real money movements. Bradesco enforces industry-leading security standards — primarily OAuth 2.0 with the FAPI (Financial-grade API) security profile and mTLS (Mutual TLS). Understanding and correctly implementing these is the difference between a secure production integration and a critical vulnerability.

OAuth 2.0: The Foundation

OAuth 2.0 is the authorization framework underlying all Bradesco API access. The key grant types you'll encounter are:

  • Client Credentials — Server-to-server API calls where no user is involved (e.g., generating boletos, querying payment status). Your app authenticates as itself.
  • Authorization Code + PKCE — User-facing flows where a customer authorizes your app to access their data (Open Banking consent). PKCE prevents authorization code interception attacks.
  • Refresh Token — Obtaining new access tokens without re-prompting the user, within the consented scope and validity period.

What is mTLS and Why Does Bradesco Require It?

Standard TLS (HTTPS) authenticates only the server to the client. Mutual TLS goes further — it requires the client to also present a certificate, proving its identity to the server.

For financial APIs, this provides critical protections:

  • Prevents unauthorized parties from using stolen OAuth tokens (token binding)
  • Ensures only registered, certificated clients can call the API
  • Satisfies regulatory requirements for financial-grade security (FAPI)

Setting Up Your mTLS Certificate

Here's the process to obtain and configure your mTLS certificate for Bradesco APIs:

  1. Generate a key pair — Create a private key and Certificate Signing Request (CSR) using OpenSSL: openssl req -new -newkey rsa:2048 -keyout client.key -out client.csr
  2. Register the CSR — Submit the CSR through Bradesco's developer portal or Open Finance registration process. The certificate is signed by the appropriate CA.
  3. Receive your certificate — Download the signed .crt or .pem file.
  4. Configure your HTTP client — Include both the certificate and private key in all API requests.

In most HTTP libraries (e.g., Python's requests, Node.js https, Java's OkHttp), you configure mTLS by providing a cert path (certificate + key) when creating the HTTPS connection.

FAPI Security Profile Requirements

Bradesco follows the FAPI 1.0 Advanced profile for Open Banking. Key requirements include:

Requirement Why It Matters
mTLS on all endpoints Client authentication and token binding
PKCE in Auth Code flows Prevents authorization code theft
Signed JWT requests (JAR) Ensures request integrity and non-repudiation
Short-lived access tokens Limits exposure window of stolen tokens
JWK endpoint for key discovery Enables dynamic key rotation without downtime

Common Security Mistakes to Avoid

  • Storing credentials in code — Always use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Skipping certificate validation — Never set verify=False or equivalent in production — this defeats TLS entirely.
  • Not rotating secrets — Establish a schedule for rotating Client Secrets and renewing certificates before expiry.
  • Overly broad scopes — Request only the minimum OAuth scopes required for your use case.
  • Logging sensitive data — Never log access tokens, private keys, or full API responses containing PII.

Token Management Best Practices

Implement a token cache in your application to reuse access tokens until they expire, rather than fetching a new token on every request. This reduces latency and avoids hitting rate limits on the token endpoint. Before using a cached token, check its expires_in value and proactively refresh it a few seconds before expiry.