Autenticação

De que forma o Asaas identifica quem é você?

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.

🚧

Atenção:

  • Após a geração da chave de API em nossa interface, armazene-a diretamente em seu cofre de chaves, evitando que seja exposta em mensagens de qualquer tipo ou emails. Nunca deixe a chave de API diretamente no código fonte de seus sistemas.
  • Não informe sua chave de API em atendimentos, a terceiros ou exponha no front-end da sua aplicação. Garanta que sua aplicação não exponha a chave em logs de sistema.
  • Caso seu time de desenvolvimento utilize a chave de API de Produção nos ambientes de desenvolvimento ou homologação durante os testes finais da integração, é essencial renová-la antes da entrada em produção, garantindo que o menor número de pessoas possível tenha acesso a ela.
  • Utilize pelo menos um dos mecanismos adicionais de segurança descritos aqui.
  • A chave de API é irrecuperável, caso seja perdida, é necessário a geração de uma nova.

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.

📘

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.

Para obter sua Chave de API acesse a área de integrações em nossa interface web. Pelo aplicativo não tem a opção de gerar chave. Além disso, apenas usuários do tipo administrador, tem permissão para gerar a chave.

Imagem mostrando onde é possível gerar a chave de API no Asaas

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:

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://sandbox.asaas.com/api/v3”, alterando para produção apenas após a validação de todas as funcionalidades.

Armazenamento seguro para a Chave de API

A Chave de API do Asaas segue o modelo de chave “irrecuperável”, isto é, ela será exibida apenas uma vez quando criada. Sendo assim, você precisará copiá-la e salvá-la de modo seguro antes de sair da área de integrações.

  • Nunca armazene chaves de API em texto claro dentro do código-fonte ou em arquivos de configuração acessíveis ao público.

  • Utilize mecanismos de segurança, como variáveis de ambiente ou arquivos de configuração protegidos, para armazenar as chaves de API de forma segura.

  • Utilize serviços de gerenciamento de segredos para armazenar e gerenciar as chaves de API de forma centralizada e segura, como AWS Secrets Manager, Google Cloud Secret Manager e Azure Key Vault, por exemplo.

Transmissão segura da sua Chave de API

  • Utilize exclusivamente protocolos de comunicação seguros, como HTTPS, evitando métodos não criptografados, como HTTP.

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.

Controle de acesso e rotação de chave

  • O acesso à Chave de API deve ser concedido apenas a usuários ou sistemas autorizados que realmente necessitam de acesso aos recursos protegidos.
  • Estabeleça um processo de monitoramento dos logs a fim de rastrear a origem e propósito das requisições, de modo a detectar atividades suspeitas ou uso indevido de sua Chave de API. Ferramentas como SIEM, Splunk, ELK Stack, AWS CloudWatch ou Azure Monitor podem auxiliar no processo.
  • Estabeleça uma política de rotação regular das chaves de API para reduzir o impacto em caso de comprometimento ou vazamento.
  • O armazenamento e segurança da chave apikey é de inteira responsabilidade do cliente, visto que o Asaas não detém dessa informação armazenada em nenhum local de nosso banco.