---
updatedAt: 2026-10-13T13:40:06.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# Authentication

How does Asaas identify who you are?

# 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`.

<Callout icon="📘" theme="info">
  By the end of this guide, you will know how to configure the headers, choose the correct environment, and identify the main authentication errors.
</Callout>

## Before you start

<Anchor target="_blank" href="https://docs.asaas.com/docs/api-keys">Create an API key</Anchor> 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 <Anchor target="_blank" href="https://docs.asaas.com/docs/additional-security-mechanisms">additional security mechanisms</Anchor>.

<Callout icon="⚠️" theme="warn">
  Never expose your API key in public code, frontend applications, images, logs, or repositories.
</Callout>

## Configure the headers

Send the following headers:

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

<br />

| Header         | Usage                                                          |
| -------------- | -------------------------------------------------------------- |
| `access_token` | The account's API key. Required in all authenticated requests. |
| `User-Agent`   | Identifies the application responsible for the request.        |
| `Content-Type` | Use `application/json` in requests that send a JSON body.      |

<Callout icon="🚧" theme="warn">
  ### Sending the User-Agent

  The `User-Agent` header is required for new root accounts created on or after **06/13/2024**.

  Use a value that identifies your application, especially when your framework does not set this header automatically.

  See <Anchor target="_blank" href="https://docs.asaas.com/docs/authentication-2#sending-the-user-agent">How to set the User-Agent</Anchor>.
</Callout>

## Choose the environment

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

| Environment | Base URL                           |
| ----------- | ---------------------------------- |
| Sandbox     | `https://api-sandbox.asaas.com/v3` |
| Production  | `https://api.asaas.com/v3`         |

<Callout icon="📘" theme="info">
  Sandbox and Production API keys are different.

  When changing the environment, also update the key used in the `access_token` header.
</Callout>

## Test the endpoints in this documentation

<Callout icon="❗️" theme="error">
  ### Use a Sandbox key

  Tests run directly from the API reference use the Sandbox environment.

  To test the endpoints, <Anchor target="_blank" href="https://sandbox.asaas.com/onboarding/createAccount?customerSignUpOriginChannel=HOME">create a Sandbox account</Anchor> and use the API key from that environment.

  A Production key will return `401 Unauthorized`.

  <Anchor target="_blank" href="https://docs.asaas.com/docs/sandbox-2">Learn more about the Sandbox</Anchor>.
</Callout>

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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

* <Anchor target="_blank" href="https://docs.asaas.com/docs/api-keys">Create and manage your API keys</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/sandbox-2">Learn about the Sandbox environment</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/additional-security-mechanisms">Configure additional security mechanisms</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/postman-en">Test the API with Postman</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/reference">Check the API reference</Anchor>

<br />

# Sibling pages

* [API Keys](https://docs.asaas.com/docs/api-keys.md)
* [PCI-DSS](https://docs.asaas.com/docs/pci-dss.md)
* [Additional security mechanisms](https://docs.asaas.com/docs/additional-security-mechanisms.md)