Whitelist de IPs
Configure uma whitelist de IPs
A whitelist permite definir quais endereços IP podem realizar requisições utilizando sua chave de API.
Requisições originadas de IPs não autorizados serão recusadas com 403 Forbidden.
Ao concluir este guia, você terá restringido o uso das suas chaves de API aos IPs cadastrados.
Quando utilizar
Utilize a whitelist para limitar o acesso à API à infraestrutura da sua aplicação.
Mesmo que uma chave seja comprometida, ela não poderá ser utilizada a partir de um IP não autorizado.
Antes de configurar, identifique os IPs públicos de saída utilizados pela sua aplicação.
1. Acesse a configuração
Acesse Menu do usuário > Integrações > Mecanismos de segurança.
2. Cadastre os IPs autorizados
Você pode cadastrar um endereço individual ou um intervalo.
| Configuração | Quando utilizar | Exemplo |
|---|---|---|
| IP único | Para autorizar um endereço específico | 192.168.1.10 |
| Intervalo de IPs | Para autorizar uma sequência de endereços | 192.168.1.10 até 192.168.1.20 |
Ao cadastrar um intervalo:
- a diferença entre o IP inicial e o final não pode ultrapassar 50 endereços;
- os intervalos não podem se sobrepor;
- um mesmo IP não pode fazer parte de mais de uma regra.
Por exemplo, caso o intervalo 192.168.1.10 até 192.168.1.20 já esteja cadastrado, não será possível adicionar o intervalo 192.168.1.15 até 192.168.1.25.
Evite intervalos amplosAutorize somente os endereços necessários para sua integração.
Faixas amplas, especialmente de provedores de nuvem, podem incluir servidores que não estão sob seu controle e reduzir a proteção oferecida pela whitelist.
Aplicações hospedadas em nuvem
Caso sua infraestrutura utilize IPs de saída dinâmicos, configure um IP estático.
Em ambientes como AWS, Google Cloud ou Azure, uma alternativa é utilizar um NAT Gateway para concentrar a saída em um único endereço ou em um conjunto controlado de IPs.
Como confirmar a configuração
Após salvar a whitelist:
- requisições originadas dos IPs cadastrados continuarão sendo processadas;
- requisições originadas de outros IPs retornarão
403 Forbidden.
Teste a configuração antes de aplicá-la definitivamente em fluxos críticos.
Confirme que todos os servidores e serviços utilizados pela integração estão contemplados antes de ativar a restrição.
Um IP ausente pode interromper as chamadas da sua aplicação.
Automatize operações de saque
Por padrão, operações de retirada solicitadas pela API geram um evento crítico e aguardam aprovação manual pela interface web ou pelo aplicativo.
Na configuração da whitelist, localize a seção Evento crítico em requisições de saque.
| Configuração | Comportamento |
|---|---|
| Ativado | As operações continuam aguardando aprovação manual, mesmo quando originadas de um IP autorizado |
| Desativado | As operações originadas dos IPs autorizados são processadas sem aprovação manual |
Proteja os saques automatizadosDesativar o evento crítico remove uma etapa de aprovação humana.
Para manter uma validação adicional, configure o mecanismo de autorização de saques por Webhook.
Operações consideradas como saque
A configuração se aplica a:
- transferências Pix e TED;
- pagamentos de contas;
- recargas de celular;
- autorizações de Pix Indireto ou Iniciação;
- estornos Pix.
Subcontas e alterações da configuração
A configuração da conta-pai é herdada pelas subcontas.
Caso a conta-pai desative o evento crítico para seus IPs, as operações das subcontas originadas desses mesmos endereços também poderão ser processadas automaticamente.
Por segurança, alterações nessa configuração exigem validação por token.
Precisa de ajuda com sua arquitetura?
Caso sua aplicação não consiga utilizar um IP de saída fixo e um NAT Gateway não seja adequado ao cenário, envie os detalhes pelo formulário.
As informações serão utilizadas pelo time de Produto para avaliar alternativas de segurança para esses casos.
Próximos passos
Updated 4 days ago