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 chave de API é de responsabilidade do cliente. Para garantir a 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.

🚧

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.

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.