Authenticate your API requests

The Asaas API uses an API key to identify the account responsible for the request.

Send the key in the access_token header. If it is missing, invalid, or does not belong to the environment being used, the API will return 401 Unauthorized.

Before you start

Create an API key in the environment you will use.

Keeping the key secure is your application's responsibility. Store it securely and consider restricting the authorized IPs.

Also see the additional security mechanisms.

Configure the headers

Send the following headers:

{
  "Content-Type": "application/json",
  "User-Agent": "your_application_name",
  "access_token": "your_api_key"
}

Choose the environment

Use the URL that matches your API key's environment:

Test the endpoints in this documentation

During development, use fictitious data and validate your integration in the Sandbox before switching the URL and the key to Production.

TLS security requirements

The Asaas API accepts connections using TLS 1.2 and TLS 1.3.

We recommend using TLS 1.3 whenever it is supported.

Authentication errors

A 401 Unauthorized response indicates that the request could not be authenticated.

Key used in the wrong environment

{
  "errors": [
    {
      "code": "invalid_environment",
      "description": "The provided API key does not belong to this environment"
    }
  ]
}

How to fix it: confirm that the URL and the key belong to the same environment.

• Production: key starting with $aact_prod_
• Sandbox: key starting with $aact_hmlg_

Missing authentication header

{
  "errors": [
    {
      "code": "access_token_not_found",
      "description": "The 'access_token' authentication header is required and was not found in the request"
    }
  ]
}

How to fix it: send the access_token header in all authenticated requests.

Incorrect key format

{
  "errors": [
    {
      "code": "invalid_access_token_format",
      "description": "The provided value does not appear to be a valid Asaas API key. Check your key's format"
    }
  ]
}

How to fix it: check whether the key contains spaces or extra characters, or was copied incompletely.

Invalid or revoked key

{
  "errors": [
    {
      "code": "invalid_access_token",
      "description": "The provided API key is invalid"
    }
  ]
}

How to fix it: confirm that the key is correct and has not been disabled, expired, or deleted.

Next steps

• Create and manage your API keys
• Learn about the Sandbox environment
• Configure additional security mechanisms
• Test the API with Postman
• Check the API reference