Autenticação

Configure a autenticação da API do Asaas com uma chave de API, envie os headers corretos e resolva erros 401 Unauthorized durante os testes.

Pré-requisitos

1. Acesse o Asaas pela interface web, não pelo aplicativo.
2. Use um usuário administrador para acessar Integrações.
3. Crie uma conta Sandbox quando for testar chamadas na documentação: https://sandbox.asaas.com.
4. Guarde a chave de API em um cofre de chaves ou gerenciador de segredos assim que ela for exibida.

Fluxo recomendado de autenticação

1. Gere a chave de API no ambiente em que você vai usar a integração.
2. Configure a URL base correspondente ao mesmo ambiente da chave.
3. Envie a chave no header HTTP access_token em todas as requisições.
4. Envie também Content-Type: application/json e um User-Agent que identifique sua aplicação.
5. Teste primeiro no Sandbox e migre para produção somente após validar o fluxo completo.

Como enviar a chave de API

Use o header access_token. O Asaas não utiliza o padrão Authorization: Bearer para autenticação com chave de API.

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

Exemplo com cURL no Sandbox

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

Se a autenticação estiver correta, a API processará a chamada no Sandbox e retornará o status e o corpo JSON do endpoint consultado. Se a chave estiver ausente, inválida ou for de outro ambiente, a resposta será 401 Unauthorized com uma mensagem de erro no corpo da resposta.

Como gerar sua chave de API

1. Acesse a interface web do Asaas.
2. Entre com um usuário administrador.
3. Vá em Integrações > Chave de API.
4. Clique em Gerar nova chave de API.
5. Copie a chave no momento da geração e armazene-a em um cofre de chaves.

A chave de API é uma informação sensível da sua conta. O Asaas não consegue gerar essa chave por você em atendimento, e a chave não pode ser gerada pelo aplicativo.

Por que não encontro a aba de integração?

O menu Integrações aparece apenas para usuários administradores. Se você não encontrar essa opção na interface web, solicite que um administrador da conta ajuste seu acesso ou gere a chave para a integração.

Por que a chave desaparece ao atualizar a página?

A chave de API é exibida apenas no momento da geração por segurança. Depois que você atualiza a página ou sai da área de integrações, a chave completa deixa de ficar visível.

Se você perder a chave, gere uma nova e substitua a chave antiga nos sistemas que usam a integração.

Impacto operacional ao gerar ou substituir uma chave

Quando uma chave é invalidada, excluída ou substituída por uma nova chave, qualquer sistema que ainda use a chave anterior passará a receber 401 Unauthorized. Planeje a troca para evitar interrupções nas integrações em produção.

Para reduzir risco durante uma rotação de chave:

1. Crie ou gere a nova chave antes de alterar sua aplicação.
2. Atualize a chave no cofre de segredos, variáveis de ambiente ou configuração protegida usada pela aplicação.
3. Faça o deploy da aplicação com a nova chave.
4. Teste uma chamada autenticada no ambiente correto.
5. Desabilite ou remova a chave antiga somente depois de confirmar que a nova chave está em uso.

Você pode criar até 10 chaves de API para uma conta Asaas. Use nomes claros para identificar a finalidade de cada chave quando esse recurso estiver disponível na sua conta.

Como recuperar uma chave de API perdida

Não é possível recuperar uma chave de API perdida, porque ela é irrecuperável após a criação. Gere uma nova chave e atualize todos os sistemas que dependiam da chave anterior.

Recebendo erro 401: o que verificar

O erro 401 Unauthorized indica que a autenticação da chamada não foi validada. Use o checklist abaixo antes de gerar uma nova chave.

1. Confirme que você está enviando o header access_token.
2. Confirme que o nome do header está escrito exatamente como access_token.
3. Confirme que você não está usando Authorization: Bearer.
4. Confirme que a chave corresponde ao ambiente da URL base.
5. Confirme que o caractere $ no início da chave foi mantido.
6. Confirme que não há espaços extras antes ou depois da chave.
7. Confirme que a chave não foi desabilitada, expirada, excluída ou substituída.
8. Gere uma nova chave apenas depois de validar os itens anteriores.

Erro por chave de ambiente incorreto

Esse erro ocorre quando você usa uma chave de produção em Sandbox ou uma chave de Sandbox em produção.

{
  "errors": [
    {
      "code": "invalid_environment",
      "description": "A chave de API informada não pertence a este ambiente"
    }
  ]
}

Corrija usando a chave e a URL base do mesmo ambiente:

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

Erro por header ausente

Esse erro ocorre quando a requisição não envia o header access_token.

{
  "errors": [
    {
      "code": "access_token_not_found",
      "description": "O cabeçalho de autenticação 'access_token' é obrigatório e não foi encontrado na requisição"
    }
  ]
}

Adicione o header access_token em todas as chamadas para a API.

Erro por formato de chave inválido

Esse erro ocorre quando a chave foi copiada com formato incorreto, teve caracteres removidos ou recebeu espaços extras.

{
  "errors": [
    {
      "code": "invalid_access_token_format",
      "description": "O valor fornecido não parece ser uma chave de API válida do Asaas. Verifique o formato da sua chave"
    }
  ]
}

Verifique se a chave começa com $aact_hmlg_ no Sandbox ou $aact_prod_ em produção.

Erro por chave inválida ou revogada

Esse erro ocorre quando a chave não existe mais, foi desabilitada, expirada, excluída ou substituída.

{
  "errors": [
    {
      "code": "invalid_access_token",
      "description": "A chave de API fornecida é inválida"
    }
  ]
}

Confirme a situação da chave no painel Asaas em Integrações > Chave de API. Se a chave não puder mais ser usada, gere uma nova e atualize sua aplicação.

Como definir o User-Agent

O header User-Agent identifica a aplicação cliente que está chamando a API. Ele pode incluir o nome da aplicação, versão, linguagem, framework e ambiente.

Para novas contas raiz criadas a partir de 13/06/2024, é obrigatório enviar User-Agent no header das requisições. Mesmo quando seu framework define um valor padrão, recomendamos complementar o valor para facilitar suporte e rastreamento.

Sintaxe sugerida:

User-Agent: <nome-aplicacao>/<versao> (<informacoes-adicionais>)

Exemplos:

• User-Agent: MinhaLoja/1.0.3 (Node.js; produção)
• User-Agent: ERPInterno/2.1 (Java_17; staging)
• User-Agent: PortalParceiros/4.5.0 (PHP; sandbox)

Armazenamento seguro da chave de API

A segurança da chave de API é responsabilidade do cliente. Trate a chave como uma credencial de produção.

• Armazene a chave em variáveis de ambiente, arquivos de configuração protegidos ou gerenciadores de segredos.
• Nunca deixe a chave diretamente no código-fonte.
• Nunca exponha a chave no front-end da sua aplicação.
• Nunca envie a chave em mensagens, emails, tickets ou canais de atendimento.
• Revise logs da aplicação para garantir que a chave não esteja sendo registrada.
• Use HTTPS em todas as chamadas para a API.

Próximos passos

• Leia o guia de autenticação principal: Autenticação com API Key.
• Configure boas práticas adicionais: Mecanismos adicionais de segurança.
• Saiba mais sobre testes: Sandbox.
• Consulte códigos de resposta: Códigos HTTP das respostas.