Autenticação

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.

📘

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.

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.