Authentication

Authentication in our API is done through the use of an API key. It is through this key that our system identifies your account and allows communication with us on behalf of the account in question.

If the API key is invalid, not provided, or the header is incorrect, our API will return HTTP 401.

🚧

Attention:

• After generating the API key in our interface, store it directly in your key vault, avoiding exposure in messages of any kind or emails. Never leave the API key directly in the source code of your systems.
• Do not provide your API key in support requests, to third parties, or expose it in your application's front end. Ensure your application does not expose the key in system logs.
• If your development team uses the Production API key in development or staging environments during final integration tests, it is essential to renew it before entering production, ensuring that as few people as possible have access to it.
• Use at least one of the additional security mechanisms described here.
• The API key is unrecoverable; if lost, it is necessary to generate a new one.

Use the headers below in all your API calls

"Content-Type": "application/json",
"User-Agent": "your_app_name",
"access_token": "your_api_key"

🚧

Warning

It is mandatory to send the User-Agent in the header of all requests in new root accounts created from 06/11/2024. We suggest sending the name of your application if your framework does not add a default User-Agent.

📘

API Keys are distinct between Sandbox and Production environments, so remember to change it when changing the URL.

To obtain your API Key access the integrations area in our web interface.

Production and Sandbox URLs

After creating the account and generating the API key, use the specific URL for each environment in your calls, as listed below:

Testing in Sandbox Environment

• During integration development, test requests in our Sandbox environment using fictitious data and directing requests to the domain "https://sandbox.asaas.com/api/v3", switching to production only after validating all functionalities.

Secure Storage for the API Key

The Asaas API Key follows the "non-recoverable" key model, that is, it will be displayed only once when created. Therefore, you need to copy and save it securely before leaving the integrations area.

• Never store API keys in plain text within source code or in configuration files accessible to the public.
• Use security mechanisms such as environment variables or protected configuration files to store API keys securely.
• Use secret management services to store and manage API keys centrally and securely, such as AWS Secrets Manager, Google Cloud Secret Manager, and Azure Key Vault, for example.

Secure Transmission of your API Key

• Use exclusively secure communication protocols, such as HTTPS, avoiding unencrypted methods such as HTTP.

TLS (Transport Layer Security) Security Protocol

Currently, our production systems accept TLS 1.2 and 1.3 for communication. But we recommend using TLS 1.3.

Access Control and Key Rotation

• Access to the API Key should be granted only to authorized users or systems that really need access to protected resources.
• Establish a monitoring process of logs to track the origin and purpose of requests, in order to detect suspicious activities or misuse of your API Key. Tools such as SIEM, Splunk, ELK Stack, AWS CloudWatch, or Azure Monitor can assist in the process.
• Establish a regular key rotation policy to reduce the impact in case of compromise or leakage.