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.

The API key is the customer's responsibility. To ensure security, we recommend that you also use other available protection mechanisms. Consider setting authorized IP addresses to add an extra layer of security. For more details, see the security measures in the documentation: Additional security mechanisms.

🚧

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. The application does not have the option to generate a key. Furthermore, only administrator-type users are allowed to generate the key.

Production and Sandbox URLs

🔒

Managing your API keys

• You can create up to 10 API keys for an Asaas account.
• Keys can be named to facilitate identification.
• It is possible to set an expiration date for each key.
• You can disable/enable a key at any time, without actually invalidating it.
• If the key is deleted, it is not possible to restore it.

Production URL and Sandbox

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://api-sandbox.asaas.com/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 only be granted to authorized users or systems that truly require access to protected resources.
• Establish a log monitoring process in order to track the origin and purpose of requests, in order to detect suspicious activity 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 policy of regularly rotating API keys to reduce the impact in the event of a compromise or leak.
• The storage and security of the apikey key is the sole responsibility of the customer, as Asaas does not have this information stored anywhere in our bank.