# Restrição de IP por chave de API: o que ela protege e o que ela quebra Guia · UNIFOKAL · 3 de setembro de 2026 · 7 min de leitura · Produto e integração A allowlist de IP limita o estrago de uma credencial vazada, mas quebra em CGNAT, serverless e failover. O que ela cobre, onde falha e com o que combiná-la. A ideia é simples e boa: cada credencial de API declara de quais endereços de origem ela pode ser usada, e qualquer requisição que chegue de fora dessa lista é recusada antes mesmo de o segredo ser conferido. Se a chave vazar em um repositório público, em um log de terceiro ou no laptop de alguém, ela sozinha não abre a porta: o atacante precisaria também estar saindo de um endereço que você declarou. O problema não é a ideia, é a expectativa. Times ligam a restrição de IP achando que fecharam o assunto, e descobrem em produção que o endereço de saída mudou, que a função sem servidor subiu em outra faixa, que o failover para outra região trouxe outros endereços. O resultado é uma integração fora do ar num horário ruim, com uma causa que ninguém suspeita de primeira porque o código não mudou. Este texto trata dos dois lados: onde a allowlist de IP realmente ajuda e onde ela quebra de forma previsível, para que a decisão de ligar ou não seja tomada antes e não durante o incidente. ## Segunda camada, nunca a primeira A restrição de IP é um controle de rede aplicado a uma credencial. Ela não substitui nenhuma das camadas anteriores: a chave continua precisando ser longa, aleatória, guardada em cofre e nunca embarcada em código de cliente. O que a allowlist faz é reduzir o valor de uma chave roubada, não impedir o roubo. Vale insistir nessa ordem porque a lista de riscos mais comuns em APIs, publicada pelo OWASP API Security Top 10 na edição de 2023, é dominada por falhas de autorização e de autenticação, não por falta de filtro de rede. Credencial com permissão excessiva, objeto acessível por identificador previsível ou endpoint sem checagem de propriedade continuam abertos qualquer que seja o endereço de origem. O corolário desagradável é o que ela não protege. Se quem obteve a chave está dentro da sua rede, saindo pelo mesmo gateway que a sua aplicação, o filtro simplesmente aprova. Isso cobre casos nada exóticos: um servidor comprometido no seu próprio ambiente, um contêiner vizinho, um processo de build que roda no mesmo cluster, um proxy de saída compartilhado. Contra o insider e contra o ambiente comprometido, a allowlist não faz nada, e a defesa volta a ser a de sempre, com [controle de acesso e escopo mínimo por credencial](https://unifokal.com/blog/controle-de-acesso-ao-dashboard-de-kyc). ## Os cenários que quebram, e eles são comuns O endereço de saída da sua aplicação parece uma constante, mas raramente é. Estes são os casos que mais derrubam integração. - **IP de saída dinâmico.** Instâncias que recebem endereço público efêmero mudam de endereço a cada substituição, escala ou reinício. A allowlist escrita na quinta-feira deixa de valer no primeiro deploy da semana seguinte. - **CGNAT.** Provedores que compartilham endereços entre assinantes usam a faixa 100.64.0.0/10, reservada pela [RFC 6598](https://www.rfc-editor.org/rfc/rfc6598.html) justamente para tradução em escala de operadora. Do lado de fora, milhares de clientes aparecem com o mesmo endereço público. Autorizar esse endereço é autorizar todo mundo que compartilha ele, e o valor de segurança da lista vira quase zero. - **Funções sem servidor.** Plataformas de execução sob demanda costumam sair por faixas amplas e mutáveis, publicadas como listas que o provedor atualiza sem aviso individual. Colar essas faixas na allowlist é aceitar uma lista enorme que envelhece sozinha. - **Failover regional.** O plano de continuidade sobe a aplicação em outra região, com outro conjunto de endereços de saída. A allowlist, feita para a região principal, transforma o failover em outro incidente, exatamente no momento em que ninguém tem paciência para depurar. A saída de engenharia para todos esses casos é a mesma: forçar o tráfego por um ponto de saída fixo, tipicamente um gateway NAT com endereço estático, e declarar só ele. Vale o custo quando a credencial é sensível, mas note o que aconteceu: a allowlist deixou de ser uma caixa marcada na interface e virou decisão de arquitetura de rede. Um lembrete que evita uma confusão frequente: endereços das faixas privadas descritas na [RFC 1918](https://www.rfc-editor.org/rfc/rfc1918.html), como 10.0.0.0/8 e 192.168.0.0/16, não servem de allowlist para uma API pública. Eles não são roteáveis na internet, e o que chega ao fornecedor é o endereço público que o NAT usou na saída, nunca o interno. ## Quem é o IP de origem, afinal Toda a discussão assume que quem verifica sabe qual é o endereço de origem. Nem sempre sabe. Se existe balanceador, CDN ou proxy reverso no caminho, o endereço da conexão vista pelo servidor de aplicação é o do último salto, e o endereço real do cliente viaja num cabeçalho. Esse cabeçalho é dado enviado pelo cliente, e o cliente pode escrever o que quiser nele. O cabeçalho que a maior parte dos proxies escreve, o X-Forwarded-For, nasceu como convenção e nunca teve especificação; a [RFC 7239](https://www.rfc-editor.org/rfc/rfc7239.html) foi publicada justamente para propor um substituto padronizado, o cabeçalho Forwarded. Nenhuma das duas formas torna o valor confiável por si. Um receptor que lê o primeiro endereço da lista e o trata como origem autêntica aceita qualquer origem que o atacante declarar, e a allowlist inteira vira teatro. A regra correta é contar os saltos: a aplicação precisa saber quantos proxies confiáveis existem à sua frente e ler a posição correspondente a partir do fim da cadeia, descartando o que veio antes. Isso significa que ligar a restrição de IP tem um pré-requisito de configuração explícita da borda, e que qualquer mudança na topologia de rede pede revisão desse número. Em IPv6, especificado pela [RFC 8200](https://www.rfc-editor.org/rfc/rfc8200.html), aparece outra diferença prática: um cliente costuma ter à disposição um prefixo inteiro, e o endereço específico usado numa conexão pode variar entre requisições. Allowlist de IPv6 que registra um endereço exato tende a falhar; o que faz sentido é declarar o prefixo delegado, aceitando que a granularidade é menor por natureza. ## O par natural da allowlist Restrição de IP funciona bem quando é uma peça de um conjunto, e não uma medida solitária. A primeira companheira é a rotação. Se a hipótese que justifica a allowlist é o vazamento de credencial, então o plano precisa incluir trocar a credencial vazada sem derrubar a integração. A publicação NIST SP 800-57 Part 1 Revision 5, do National Institute of Standards and Technology, formaliza esse hábito com o conceito de criptoperíodo, o intervalo durante o qual uma chave permanece autorizada. Uma allowlist muito restritiva às vezes cria a ilusão de que a rotação pode esperar, e é o contrário: as duas se complementam. A segunda é a telemetria por credencial. Sem saber de quais endereços cada chave está sendo usada, e quando foi seu último uso, montar a lista é adivinhação. O registro de uso responde às três perguntas do dia a dia: quais endereços declarar, se alguém está tentando usar a chave de fora da lista, e se uma chave antiga ainda tem tráfego. Esses dados alimentam [o acompanhamento contínuo da integração](https://unifokal.com/blog/monitoramento-de-integracao-de-kyc), onde a subida de recusas por origem não autorizada é um alerta de primeira linha. A terceira é a separação de ambientes. Credencial de teste e credencial de produção saem de lugares diferentes, e uma allowlist por ambiente é mais fácil de manter do que uma lista única cheia de exceções. É mais um motivo, entre os já conhecidos, para [manter sandbox e produção realmente separados](https://unifokal.com/blog/separar-sandbox-de-producao), inclusive na topologia de saída. Por fim, uma escolha de produto que muda a experiência: aplicar a restrição como configuração da credencial, e não da conta inteira. Assim uma chave de integração servidor a servidor pode ter lista estreita enquanto uma chave administrativa, operada de redes variáveis, fica sem restrição e compensa com escopo menor e prazo curto. Em plataformas de verificação de identidade, incluindo a UNIFOKAL, é essa granularidade que torna a allowlist utilizável, em vez de um botão que ninguém liga por medo de derrubar o cadastro. ## Fontes citadas - [RFC 1918: Address Allocation for Private Internets](https://www.rfc-editor.org/rfc/rfc1918.html), IETF. - [RFC 6598: IANA-Reserved IPv4 Prefix for Shared Address Space](https://www.rfc-editor.org/rfc/rfc6598.html), IETF. - [RFC 7239: Forwarded HTTP Extension](https://www.rfc-editor.org/rfc/rfc7239.html), IETF. - [RFC 8200: Internet Protocol, Version 6 (IPv6) Specification](https://www.rfc-editor.org/rfc/rfc8200.html), IETF. - [NIST SP 800-57 Part 1: Recommendation for Key Management](https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final), National Institute of Standards and Technology. - OWASP API Security Top 10, edição de 2023, lista de riscos mais comuns em APIs, citada por nome no texto.