Crie e gerencie suas chaves de API

A chave de API identifica sua conta e autoriza as requisições enviadas à API do Asaas.

Antes de começar

A chave de API:

• deve ser criada pela interface web do Asaas;
• não pode ser gerada pelo aplicativo;
• somente pode ser criada por usuários administradores;
• é exclusiva do ambiente em que foi gerada.

Crie uma chave de API

Acesse a área de Integrações pela interface web para criar sua chave.

Gerencie suas chaves

Uma conta Asaas pode ter até 10 chaves de API.

Para cada chave, você pode:

• definir um nome para identificação;
• configurar uma data de expiração;
• desabilitar ou habilitar temporariamente;
• excluir quando não for mais utilizada.

Escolha o ambiente

Utilize a URL correspondente ao ambiente da sua chave:

Durante o desenvolvimento, utilize o Sandbox com dados fictícios. Altere para Produção somente após validar todos os fluxos da integração.

Armazene a chave com segurança

Não armazene a chave:

• diretamente no código-fonte;
• em aplicações frontend;
• em arquivos públicos;
• em logs;
• em mensagens, e-mails ou repositórios;
• em workspaces ou ferramentas compartilhadas sem proteção.

Prefira:

• variáveis de ambiente;
• arquivos de configuração protegidos;
• serviços de gerenciamento de segredos, como AWS Secrets Manager, Google Cloud Secret Manager ou Azure Key Vault.

Utilize sempre HTTPS para transmitir informações de autenticação.

Controle o acesso e faça a rotação das chaves

Permita o acesso somente às pessoas e aos sistemas que realmente precisam utilizar a chave.

Também recomendamos:

• monitorar a origem das requisições;
• revisar acessos periodicamente;
• definir uma política de rotação;
• renovar chaves utilizadas por muitas pessoas durante o desenvolvimento;
• substituir imediatamente uma chave que possa ter sido exposta.

A segurança e o armazenamento da chave são de responsabilidade do cliente.

Ciclo de vida por inatividade

Chaves que permanecem sem uso por longos períodos são desabilitadas ou expiradas automaticamente.

Essas regras se aplicam a contas-pai e subcontas.

Após 3 meses

A chave é desabilitada e deixa de autenticar requisições.

As chamadas realizadas com ela retornarão 401 Unauthorized.

Você pode habilitá-la novamente em Integrações > Chaves de API.

O Asaas envia:

• aviso por e-mail;
• evento ACCESS_TOKEN_DISABLED.

Após 6 meses

A chave é expirada permanentemente e não pode ser reativada.

Para continuar utilizando a integração, crie uma nova chave.

O Asaas envia:

• aviso por e-mail;
• evento ACCESS_TOKEN_EXPIRED.

Alertas de proximidade da expiração

O evento ACCESS_TOKEN_EXPIRING_SOON é enviado:

• após 4 meses de inatividade;
• após 5 meses de inatividade;
• uma semana antes da expiração.

Consulte os eventos de Webhook para chaves de API para conhecer os payloads.

Exceção para operações BaaS

Para essas contas:

• os avisos por e-mail não são enviados;
• somente os eventos de Webhook são disparados;
• a conta-pai deve monitorar o evento ACCESS_TOKEN_EXPIRED nas subcontas.

Gerencie chaves de subcontas pela API

A conta-pai pode criar, listar, atualizar e revogar chaves de API de suas subcontas.

Esse fluxo permite substituir chaves expiradas sem acessar manualmente cada conta.

Consulte Gerenciamento de chaves de API de subcontas.

Adicione outras camadas de segurança

Além da chave de API, recomendamos configurar pelo menos um mecanismo adicional de segurança.

Whitelist de IPs

Permite definir os endereços IP autorizados a utilizar a chave.

Requisições originadas de IPs não cadastrados são recusadas com 403 Forbidden.

Configure a whitelist de IPs.

Autorização de transferências por Webhook

Permite que sua aplicação valide as transferências solicitadas na conta.

Caso o sistema não reconheça uma transferência como legítima, ela pode ser rejeitada.

Configure a validação de transferências por Webhook.

Próximos passos

• Autentique suas requisições
• Conheça os mecanismos adicionais de segurança
• Configure a whitelist de IPs
• Gerencie chaves de subcontas
• Conheça o Sandbox