A autenticação em nossa API é feita através do uso de uma chave de API. É através desta chave que nosso sistema identifica a sua conta e permite a comunicação conosco em nome da conta em questão.

Caso a chave de API seja inválida, não seja informada ou o header esteja incorreto, nossa API retornará HTTP 401.

A segurança da chave de API é de responsabilidade do cliente. Para reforçar sua segurança, recomendamos que você utilize também os demais mecanismos de proteção disponíveis. Considere definir endereços IP autorizados para adicionar uma camada extra de segurança. Para mais detalhes, consulte as medidas de segurança na documentação: Mecanismos adicionais de segurança.

Veja como criar uma chave acessando o guia Chaves de API.

Utilize os headers abaixo em todas as suas chamadas para a API

"Content-Type": "application/json",
"User-Agent": "nome_da_sua_aplicação",
"access_token": "sua_api_key"

🚧

Importante

É obrigatório enviar o User-Agent no header de todas as requisições em novas contas raiz criadas a partir de 13/06/2024. Sugerimos enviar o nome da sua aplicação caso o seu framework não adicione um User-Agent padrão.

O User-Agent é um cabeçalho que ajuda a identificar sua aplicação nas requisições à API. Personalizar esse valor facilita rastrear a origem das chamadas.

Saiba mais sobre como definir seu User-Agent aqui: Como posso definir meu user-agent?

❗️

ATENÇÃO: Para testar os endpoints direto nesta documentação você precisa de uma chave de API de Sandbox

Caso seja utilizada a chave de produção, obterá o erro401 Unauthorized.

Todos os endpoints da documentação apontam para nosso Sandbox, o ambiente de testes do Asaas. Antes de começar você deve criar uma conta de testes e usar sua chave de API para testes.

Saiba mais sobre o Sandbox

URL de Produção e Sandbox

Após a criação da conta e geração da chave de API, utilize a URL específica para cada ambiente em suas chamadas, conforme listado abaixo:

📘

Ambientes distintos (Sandbox e Produção)

As Chaves de API são distintas entre os ambientes de Sandbox e Produção, portanto lembre-se de alterá-la quando mudar a URL.

Teste em ambiente Sandbox

• Durante o desenvolvimento da integração, teste as requisições em nosso ambiente de Sandbox utilizando dados fictícios e direcionando as requisições para o domínio “https://api-sandbox.asaas.com/v3", alterando para produção apenas após a validação de todas as funcionalidades.

Protocolo de segurança TLS (Transport Layer Security)

Atualmente nossos sistemas em produção aceitam TLS 1.2 e 1.3 para comunicação. Mas recomendamos o uso do TLS 1.3.

Erros de autenticação

Uma resposta 401 Unauthorized indica que sua requisição não pôde ser autenticada. Para te ajudar a diagnosticar o problema rapidamente, nossa API retorna um corpo de erro com uma mensagem específica para cada cenário.

Abaixo estão as causas mais comuns e as mensagens de erro correspondentes:

Uso de chave em ambiente incorreto

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

Como resolver?

Verifique se você está usando sua chave de Produção ($aact_prod_...) nos endpoints de produção (api.asaas.com) e sua chave de Sandbox ($aact_hmlg_...) nos endpoints de Sandbox (api-sandbox.asaas.com).

Cabeçalho de autenticação ausente

{
  "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"
    }
  ]
}

Como resolver?

Garanta que o cabeçalho access_token está sendo enviado corretamente em todas as suas requisições.

Formato da chave incorreto

{
  "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"
    }
  ]
}

Como resolver?

Verifique se você não copiou espaços extras ou caracteres a mais. Chaves de produção começam com $aact_prod_ e as de Sandbox com $aact_hmlg_.

Chave de API inválida ou revogada

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

Como resolver?

Confirme se o valor da chave de API que você está enviando está correto e se ela não foi desabilitada, expirada ou excluída no seu painel Asaas.