Authentication

Configure Asaas API authentication with an API key, send the correct headers, and resolve 401 Unauthorized errors during testing.

Prerequisites

1. Access Asaas via the web interface, not the mobile app.
2. Use an administrator user to access Integrations.
3. Create a Sandbox account when testing calls in the documentation: https://sandbox.asaas.com.
4. Store the API key in a key vault or secrets manager as soon as it is displayed.

Recommended Authentication Flow

1. Generate the API key in the environment where you will use the integration.
2. Configure the base URL corresponding to the same environment as the key.
3. Send the key in the access_token HTTP header on every request.
4. Also send Content-Type: application/json and a User-Agent that identifies your application.
5. Test in Sandbox first and migrate to production only after validating the complete flow.

How to Send the API Key

Use the access_token header. Asaas does not use the Authorization: Bearer standard for API key authentication.

Content-Type: application/json
User-Agent: MyStore/1.0.3 (Node.js; sandbox)
access_token: $aact_hmlg_xxxxxxxxxxxxxxxxxx

cURL Example in Sandbox

curl --request GET \
  --url 'https://api-sandbox.asaas.com/v3/customers' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: MyStore/1.0.3 (Node.js; sandbox)' \
  --header 'access_token: $aact_hmlg_xxxxxxxxxxxxxxxxxx'

If authentication is correct, the API will process the call in Sandbox and return the status and JSON body of the queried endpoint. If the key is missing, invalid, or from a different environment, the response will be 401 Unauthorized with an error message in the response body.

How to Generate Your API Key

1. Access the Asaas web interface.
2. Log in with an administrator user.
3. Go to Integrations > API Key.
4. Click Generate new API key.
5. Copy the key at the moment of generation and store it in a key vault.

The API key is sensitive account information. Asaas cannot generate this key for you via support, and the key cannot be generated through the mobile app.

Why Can't I Find the Integration Tab?

The Integrations menu only appears for administrator users. If you cannot find this option in the web interface, ask an account administrator to adjust your access or generate the key for the integration.

Why Does the Key Disappear After Refreshing the Page?

The API key is only displayed at the moment of generation for security reasons. After you refresh the page or leave the integrations area, the full key is no longer visible.

If you lose the key, generate a new one and replace the old key in all systems using the integration.

Operational Impact When Generating or Replacing a Key

When a key is invalidated, deleted, or replaced by a new key, any system still using the previous key will start receiving 401 Unauthorized. Plan the replacement to avoid disruptions in production integrations.

To reduce risk during a key rotation:

1. Create or generate the new key before changing your application.
2. Update the key in the secrets vault, environment variables, or protected configuration used by the application.
3. Deploy the application with the new key.
4. Test an authenticated call in the correct environment.
5. Disable or remove the old key only after confirming the new key is in use.

You can create up to 10 API keys for an Asaas account. Use clear names to identify the purpose of each key when this feature is available on your account.

How to Recover a Lost API Key

It is not possible to recover a lost API key, as it is irrecoverable after creation. Generate a new key and update all systems that depended on the previous key.

Receiving a 401 Error: What to Check

The 401 Unauthorized error indicates that the call's authentication was not validated. Use the checklist below before generating a new key.

1. Confirm you are sending the access_token header.
2. Confirm the header name is spelled exactly as access_token.
3. Confirm you are not using Authorization: Bearer.
4. Confirm the key matches the environment of the base URL.
5. Confirm the $ character at the beginning of the key has been preserved.
6. Confirm there are no extra spaces before or after the key.
7. Confirm the key has not been disabled, expired, deleted, or replaced.
8. Generate a new key only after validating the items above.

Error Due to Incorrect Environment Key

This error occurs when you use a production key in Sandbox or a Sandbox key in production.

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

Fix it by using the key and base URL from the same environment:

curl --request GET \
  --url 'https://api-sandbox.asaas.com/v3/customers' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: MyStore/1.0.3 (Node.js; sandbox)' \
  --header 'access_token: $aact_hmlg_xxxxxxxxxxxxxxxxxx'

Error Due to Missing Header

This error occurs when the request does not send the access_token header.

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

Add the access_token header to all API calls.

Error Due to Invalid Key Format

This error occurs when the key was copied with an incorrect format, had characters removed, or received extra spaces.

{
  "errors": [
    {
      "code": "invalid_access_token_format",
      "description": "The provided value does not appear to be a valid Asaas API key. Please check the format of your key"
    }
  ]
}

Verify that the key starts with $aact_hmlg_ in Sandbox or $aact_prod_ in production.

Error Due to Invalid or Revoked Key

This error occurs when the key no longer exists, has been disabled, expired, deleted, or replaced.

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

Check the key status in the Asaas dashboard under Integrations > API Key. If the key can no longer be used, generate a new one and update your application.

How to Set the User-Agent

The User-Agent header identifies the client application calling the API. It can include the application name, version, language, framework, and environment.

For new root accounts created after 06/13/2024, sending User-Agent in request headers is mandatory. Even when your framework sets a default value, we recommend supplementing it to facilitate support and tracking.

Suggested syntax:

User-Agent: <application-name>/<version> (<additional-information>)

Examples:

• User-Agent: MyStore/1.0.3 (Node.js; production)
• User-Agent: InternalERP/2.1 (Java_17; staging)
• User-Agent: PartnerPortal/4.5.0 (PHP; sandbox)

Secure API Key Storage

The security of the API key is the customer's responsibility. Treat the key as a production credential.

• Store the key in environment variables, protected configuration files, or secrets managers.
• Never leave the key directly in source code.
• Never expose the key in your application's frontend.
• Never send the key in messages, emails, tickets, or support channels.
• Review application logs to ensure the key is not being recorded.
• Use HTTPS on all API calls.

Next Steps

• Read the main authentication guide: Authentication with API Key.
• Configure additional best practices: Additional Security Mechanisms.
• Learn more about testing: Sandbox.
• Check response codes: HTTP Response Codes.