Autenticação com API Key do Asaas

Introdução

No Asaas, a autenticação é realizada por meio de um header HTTP chamado access_token, que recebe o valor da sua API Key.

Diferente de outros serviços, o Asaas não utiliza o padrão:

Authorization: Bearer ...

✅ O formato correto é:

access_token: $aact_prod_xxxxxxxxxxxxxxxx

Prefixos das chaves por ambiente

As chaves de API do Asaas possuem prefixos distintos conforme o ambiente, o que garante separação clara entre produção e homologação.

Ambiente: Produção Prefixo da chave: $aact_prod_ Exemplo: $aact_prod_xxxxxxxxxxxxxxxxxx

Ambiente: Sandbox (homologação) Prefixo da chave: $aact_hmlg_ Exemplo: $aact_hmlg_xxxxxxxxxxxxxxxxxx

Atenção ao cifrão ($) na API Key

O caractere $ faz parte da API Key e nunca deve ser removido, alterado ou interpretado como variável.

Este ponto é crítico em PHP, mas deve ser considerado em qualquer linguagem. O cifrão não representa uma variável, ele é parte fixa da chave.

Por que o cifrão causa erro em algumas linguagens?

O cifrão ($) pode gerar erro em linguagens que o interpretam como início de variável, especialmente o PHP.

No PHP, quando uma string está entre aspas duplas (" "), o interpretador tenta interpolar variáveis automaticamente.

❌ Exemplo incorreto (PHP)

$apiKey = "$aact_prod_xxxxxxxxx";

Neste caso, o PHP interpreta $aact_prod_... como uma variável chamada $aact_prod_.

O resultado é que o cifrão é removido, a chave fica inválida e a requisição retorna:

401 Unauthorized

✅ Como enviar corretamente a API Key (PHP)

A forma correta é utilizar aspas simples, garantindo que o valor seja tratado como string literal, sem interpolação.

Exemplo:

$apiKey = '$aact_hmlg_xxxxxxxxxxxxxxxxxx'; // Sandbox

$headers = [
'Accept: application/json',
'Content-Type: application/json',
'access_token: ' . $apiKey,
];

$ch = curl_init('[https://api-sandbox.asaas.com/v3/customers](https://api-sandbox.asaas.com/v3/customers)');

curl_setopt_array($ch, [
CURLOPT_HTTPHEADER     => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST  => 'GET',
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

O mesmo vale para o ambiente Sandbox:

$apiKey = '$aact_hmlg_xxxxxxxxxxxxxxxxxx';

Cabeçalhos corretos e padrão do Asaas

Header: access_token Descrição: Contém a chave de API, iniciando com $aact_... Exemplo: $aact_prod_xxxxxxxxxxxxxxxxxx

Header: Content-Type Descrição: Define o tipo de conteúdo da requisição Exemplo: application/json

❗️

Não use:

Authorization: Bearer ...

Nota importante

O Asaas utiliza o formato $aact_... propositalmente, para reforçar segurança e segmentação de ambientes.

➡️ O cifrão ($) faz parte da chave ➡️ Não é uma variável ➡️ Não deve ser removido, truncado ou modificado

Essa regra vale independentemente da linguagem utilizada, mesmo que os exemplos deste guia tenham foco em clientes PHP.