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.
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:
Ambiente | URL |
---|---|
Produção | https://api.asaas.com/v3 |
Sandbox | https://sandbox.asaas.com/api/v3 |
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.
Updated 5 days ago