What authentication methods does Boleto.Cloud support?

Boleto.Cloud primarily supports API keys for server-to-server integrations and OAuth 2.0 (specifically Client Credentials and Authorization Code grants) for applications requiring delegated access.

How do I get an API key for Boleto.Cloud?

You can generate an API key by logging into your Boleto.Cloud dashboard, navigating to the 'Settings' or 'API' section, and following the instructions to create and securely store your key.

Is OAuth 2.0 required for all Boleto.Cloud integrations?

No, OAuth 2.0 is not required for all integrations. API keys are suitable for many server-to-server use cases where your application acts on its own behalf. OAuth 2.0 is generally preferred for third-party applications that need to access a user's Boleto.Cloud account with their explicit consent.

Should I expose my Boleto.Cloud API key in client-side code?

No, you should never expose your Boleto.Cloud API key or any other secret credentials in client-side code (e.g., JavaScript in a web browser or mobile app). All API calls requiring these credentials should be made from your secure backend server.

What is the recommended way to secure API keys?

The recommended way to secure API keys is to store them in environment variables, secure configuration files, or dedicated secret management services, and never hardcode them directly into your application's source code.

Does Boleto.Cloud require HTTPS for API calls?

Yes, Boleto.Cloud requires all API communication to occur over HTTPS/TLS to ensure data encryption in transit and protect sensitive information.

How often should I rotate my Boleto.Cloud API credentials?

It is a security best practice to periodically rotate your API keys and client secrets, even if there's no known compromise. This minimizes the impact if a credential is ever exposed.

Boleto.Cloud Authentication: API Key & OAuth 2.0 (2026)

Authentication overview

Boleto.Cloud secures its API endpoints through established authentication mechanisms, ensuring that only authorized applications and users can initiate financial transactions or access sensitive payment data. The primary methods supported are API keys and OAuth 2.0, catering to different integration scenarios from backend server-to-server operations to user-facing applications requiring delegated access. All API communication with Boleto.Cloud must occur over HTTPS/TLS to encrypt data in transit and prevent eavesdropping or tampering, aligning with industry best practices for financial APIs.

The choice of authentication method depends on the specific use case. For direct backend integrations where a server application accesses Boleto.Cloud on its own behalf (e.g., to issue boletos for an e-commerce platform), API keys are typically used. For applications where a user grants permission for a third-party service to act on their behalf (e.g., a financial management tool integrating with Boleto.Cloud), OAuth 2.0 provides a secure delegation framework. Understanding the appropriate method and securely managing credentials are key steps in integrating with the Boleto.Cloud API.

Supported authentication methods

Boleto.Cloud supports two main authentication methods for accessing its API:

API Keys: A simple, token-based authentication method suitable for server-to-server communication.
OAuth 2.0: An industry-standard protocol for authorization, allowing third-party applications to obtain limited access to a user's account without exposing their credentials.

API Keys

API keys are unique identifiers used to authenticate a project or application when making API requests. When using API keys with Boleto.Cloud, the key is typically included in the request header or as a query parameter. This method is straightforward and recommended for applications that operate on behalf of a single account owner and do not require user interaction for authorization, such as backend services or scheduled tasks.

OAuth 2.0

OAuth 2.0 is an authorization framework that enables an application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the application to obtain access on its own behalf. Boleto.Cloud supports specific OAuth 2.0 flows, primarily the Client Credentials Grant for server-side applications and potentially the Authorization Code Grant for user-facing applications. The OAuth 2.0 specification is maintained by the IETF.

Client Credentials Grant

This flow is used when the client (your application) is acting on its own behalf, rather than on behalf of a user. The client authenticates with the authorization server using its client ID and client secret to obtain an access token. This is suitable for server-to-server interactions where the application itself is the resource owner, or when the application has been pre-authorized to access specific resources. Boleto.Cloud's API reference details how to implement this grant type for server-side integrations.

Authorization Code Grant

This flow is designed for confidential clients (applications capable of maintaining the confidentiality of their credentials) and is the most common flow for web applications. It involves redirecting the user to Boleto.Cloud's authorization server to grant permission, after which an authorization code is returned to the client. The client then exchanges this code for an access token. This flow ensures that user credentials are not exposed to the client application.

The following table summarizes the supported authentication methods:

Method	When to Use	Security Level
API Key	Server-to-server integrations, backend services, batch processing, direct application access (without user delegation).	Medium (requires careful key management, vulnerable if key is compromised).
OAuth 2.0 (Client Credentials)	Server-to-server integrations where the application acts on its own behalf, or when specific application-level permissions are required.	High (client secret must be protected, token has limited scope and expiry).
OAuth 2.0 (Authorization Code)	User-facing web applications requiring delegated access to a user's Boleto.Cloud account, without exposing user credentials to the application.	High (tokens are short-lived, refresh tokens can be used, user consent is explicit).

Getting your credentials

To interact with the Boleto.Cloud API, you will need to obtain the necessary authentication credentials from your Boleto.Cloud account dashboard. The specific steps vary slightly depending on whether you are generating an API key or setting up an OAuth 2.0 client.

API Key

Log in to your Boleto.Cloud dashboard via the Boleto.Cloud homepage.
Navigate to the 'Settings' or 'API' section.
Look for an option to 'Generate API Key' or 'Manage API Credentials'.
Follow the on-screen instructions to generate a new API key. Ensure you copy and store this key securely immediately, as it may only be displayed once.
The Boleto.Cloud documentation provides specific guidance on API key usage.

OAuth 2.0 Client Credentials

For OAuth 2.0 integrations, you will typically need a Client ID and a Client Secret:

Log in to your Boleto.Cloud dashboard.
Navigate to the 'Developer' or 'Applications' section.
Register a new application, which will typically involve providing a name for your application and a redirect URI (for Authorization Code flow).
Upon successful registration, Boleto.Cloud will provide you with a Client ID and Client Secret. These are confidential and should be stored securely.

Always refer to the official Boleto.Cloud documentation for the most up-to-date and precise instructions on credential generation.

Authenticated request example

Below is an example of an authenticated request using an API key, targeting a hypothetical Boleto.Cloud endpoint for creating a new Boleto. This example uses curl, a common command-line tool for making HTTP requests. Replace YOUR_API_KEY and other placeholder values with your actual credentials and data.


curl -X POST \
  https://api.boleto.cloud/v1/boletos \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{ \
    "amount": 10000, \
    "customer_name": "João da Silva", \
    "customer_cpf_cnpj": "123.456.789-00", \
    "due_date": "2026-06-30", \
    "description": "Payment for services" \
  }'

This example demonstrates passing the API key in the Authorization header using the Bearer scheme, which is a common practice for token-based authentication in RESTful APIs. For specific endpoint details and required parameters, consult the Boleto.Cloud API Reference.

Security best practices

Implementing strong security practices is crucial when integrating with any payment API like Boleto.Cloud. Adhering to these guidelines helps protect your application and your users' financial data.

Protect API Keys and Secrets

Never hardcode credentials: Do not embed API keys or client secrets directly into your source code. Use environment variables, secure configuration files, or secret management services (e.g., Google Cloud Secret Manager, AWS Secrets Manager) to store and retrieve them.
Restrict access: Limit who has access to your API keys and client secrets. Implement strict access controls for development, staging, and production environments.
Rotate credentials regularly: Periodically generate new API keys and client secrets and revoke old ones. This minimizes the risk associated with a compromised key.
Avoid client-side exposure: Never expose API keys or client secrets in client-side code (e.g., JavaScript in a web browser, mobile application code) as they can be easily extracted. All API calls requiring these credentials should originate from your secure backend server.

Use HTTPS/TLS for all communication

Ensure that all communications with the Boleto.Cloud API use HTTPS (HTTP Secure) to encrypt data in transit. This prevents man-in-the-middle attacks and protects sensitive information like payment details and authentication tokens from being intercepted. Boleto.Cloud enforces HTTPS for all its API endpoints, but it's important to verify that your client application is also configured to use it.

Implement Least Privilege

Configure your API credentials with the minimum necessary permissions. For example, if your application only needs to issue boletos, ensure its API key or OAuth token only has access to relevant creation endpoints and not, for instance, to account management or refund capabilities. This limits the potential damage if a credential is compromised.

Secure Error Handling and Logging

Avoid verbose error messages: Do not include sensitive information (like API keys, internal system details, or user data) in error messages returned to clients.
Log securely: If logging API requests and responses for debugging, ensure that sensitive data and credentials are redacted or masked before being written to logs. Store logs securely and implement strict access controls.

Validate and Sanitize Inputs

Before sending data to the Boleto.Cloud API, always validate and sanitize all user-supplied inputs to prevent common web vulnerabilities like injection attacks. This includes verifying data types, formats, and acceptable ranges for all parameters.

Monitor API Usage

Regularly monitor your API usage patterns. Unusual spikes in activity, requests from unexpected IP addresses, or a high volume of failed authentication attempts could indicate a security incident. Boleto.Cloud may offer monitoring tools or logs within its dashboard, or you can implement your own monitoring solutions.

Keep SDKs and Libraries Updated

If using Boleto.Cloud's official SDKs (PHP, Java, Ruby, Python, Node.js, .NET), ensure they are kept up-to-date. Updates often include security patches and improvements that can protect your integration from newly discovered vulnerabilities.