Whitelist de IPs

Este mecanismo permite definir IPs a partir dos quais aceitaremos requisições utilizando sua chave de API.

Qualquer requisição recebida de um IP não contido na whitelist será recusada com resposta HTTP 403.

Desta forma, mesmo que sua chave seja comprometida, a menos que as requisições partam de sua infraestrutura, elas serão recusadas.

Você pode definir a sua lista de IPs autorizados acessando Menu do usuário > Integrações > Mecanismos de segurança.

📘
Tipos de configuração
Você pode cadastrar seus endereços de duas formas:

IP Único: Para liberar um endereço específico (ex: 192.168.1.10).

Intervalo de IPs: Para liberar uma sequência de endereços (ex: de 192.168.1.10 até 192.168.1.20).

Ao configurar um novo intervalo, a diferença entre o IP inicial e o final não pode exceder 50 endereços(ex: 192.168.1.1 até 192.168.1.51)

Não é permitido cadastrar intervalos que se cruzem ou que contenham IPs já liberados em outras regras da sua lista. Cada IP deve pertencer a uma única regra de configuração.

Exemplo: Se você já liberou o intervalo 192.168.1.10 até 192.168.1.20, não será possível criar uma nova regra de 192.168.1.15 até 192.168.1.25, pois os endereços entre o final 15 e o 20 se sobrepõem.

🚧
Atenção ao configurar intervalos de IPs amplos
Embora a configuração de faixas de IP seja uma ferramenta flexível, a liberação de intervalos muito grandes pode comprometer a segurança da sua conta e anular o propósito desta funcionalidade.
Risco
Uma faixa de IPs muito ampla, como a de um grande provedor de nuvem, pode incluir milhares de servidores que não estão sob o seu controle. Caso sua chave de API seja exposta, um atacante operando dentro dessa mesma faixa de IPs poderia realizar requisições válidas à sua conta.
Lembre-se que o objetivo do Whitelist de IPs é restringir o acesso ao menor conjunto de endereços possível, seguindo o princípio do menor privilégio.
Recomendação para Servidores em Nuvem
Se sua aplicação roda em um ambiente com IPs de saída dinâmicos (como AWS, GCP, Azure, etc.), recomendamos fortemente a utilização de um serviço de NAT Gateway com um IP de saída estático. Isso permite que você adicione um único IP ou um pequeno e controlado conjunto de IPs à sua whitelist, garantindo o máximo de segurança para sua integração.

Por que fixar IPs?

Fixar IPs para chamadas de API pode ser uma prática útil e necessária.

Ao fixar IPs, você pode restringir o acesso às suas APIs, permitindo chamadas apenas de IPs específicos. Isso ajuda a bloquear acessos não autorizados ou indesejados.

No entanto, isso também exige a manutenção de uma lista de IPs autorizados e pode tornar o gerenciamento de acessos mais complexo, mas garantindo muito mais segurança em suas requisições ao Asaas, especialmente em operações White Label.

Automação de saques para IPs autorizados

Por padrão, toda operação de retirada de valores (saques) solicitada via API gera um Evento Crítico. Isso significa que a transação fica pendente aguardando uma aprovação manual via Interface Web ou Aplicativo para ser efetivada.

Para facilitar a automação de grandes volumes, é possível configurar sua Whitelist de IPs para isentar determinadas origens dessa aprovação manual.

Como funciona?

Na tela de configuração de IPs, você encontrará a seção "Evento crítico em requisições de saque".

Ativado (Padrão): O sistema continua exigindo aprovação manual para saques, mesmo vindo de um IP conhecido.
Desativado: O sistema processará automaticamente as solicitações de saque vindas dos IPs listados, sem gerar pendência de aprovação manual.

🚧
Recomendações de Segurança
Ao desativar a geração de eventos críticos, você remove uma camada de verificação humana.
Para manter sua operação segura e automatizada, recomendamos fortemente a implementação conjunta do Mecanismo de Autorização Externa via Webhook. Dessa forma, você substitui a aprovação manual por uma aprovação sistêmica, garantindo que apenas transações reconhecidas pelo seu sistema sejam processadas.

Operações consideradas como saque:

Transferências (Pix e TED);
Pagamento de contas;
Recargas de celular;
Autorizações de Pix Indireto/Iniciação;
Estornos de Pix.

Regras de herança e permissão:

Esta configuração é herdada automaticamente. Se a conta-pai desativar o evento crítico para seus IPs, as requisições das subcontas originadas desses mesmos IPs também serão processadas automaticamente.
Por segurança, qualquer alteração nesta configuração exige validação de token, seguindo o mesmo rigor da adição de um novo IP.

Tem um cenário complexo e precisa de ajuda?

Entendemos que algumas arquiteturas podem ter desafios específicos para fixar um IP de saída. Se este for o seu caso e a solução de NAT Gateway não for aplicável, queremos entender melhor seu cenário.

Preencha este formulário para que nossa equipe de produto possa analisar seu caso de uso e, futuramente, desenvolvermos alternativas de segurança que atendam à sua necessidade.