IP estático para API: como resolver o erro de autorização

Ontem à noite a integração rodou: a lista de pedidos veio, o SMS saiu. Hoje de manhã o mesmo código, com a mesma chave, devolve "autorização de IP necessária" ou um 403 seco. Nada mudou no código. O que mudou foi o endereço pelo qual a requisição sai para a internet: o modem reconectou de madrugada, um colega em home office testou pela linha dele ou a aplicação foi movida para outro servidor. O serviço do outro lado só reconhece o endereço que foi informado antes.

Neste artigo explicamos como funciona a autorização de IP em APIs, em quais situações o aviso aparece e como descobrir o IP de saída que o serviço realmente enxerga. Depois comparamos em uma única tabela as quatro formas de ter um endereço de saída fixo (IP estático do provedor de internet, servidor com IP fixo, NAT gateway e proxy estático). Reservamos uma seção à parte para dizer qual caminho não deve ser escolhido em integrações de pagamento, saúde e nota fiscal eletrônica. No final há um exemplo testado em Python e Node.js que confere o endereço de saída.

O que é autorização de IP em APIs?#

Autorização de IP (lista de IPs permitidos; na documentação costuma aparecer como "IP whitelist" ou "allowlist") é quando um serviço filtra a requisição recebida pelo endereço de origem antes de olhar o conteúdo. No painel do serviço, ou nos registros da equipe de suporte, existe uma lista de endereços ligada à sua conta. Se a requisição vem de um endereço dessa lista, a chave de API é conferida; se não vem, a requisição é recusada mesmo com a chave correta.

Esse controle não substitui a chave de API, ele se soma a ela. Mesmo que a chave vá parar em um repositório por engano ou vaze do notebook de um funcionário, quem a obtiver não consegue usá-la enquanto não sair também pelo seu endereço. O que se verifica não é um cabeçalho HTTP, e sim o endereço na outra ponta da conexão TCP; não dá para mudar o endereço de origem acrescentando um cabeçalho como X-Forwarded-For.

Dois sentidos costumam se confundir aqui. Na lista que descrevemos em Autenticação de proxy: user:pass ou whitelist de IP, você informa o endereço ao seu provedor de proxy, e o objetivo é conectar ao proxy sem senha. Este artigo trata do sentido oposto: você informa o endereço ao serviço de terceiros cujos dados quer acessar. O mecanismo é o mesmo, o interlocutor é outro.

De que formas os serviços pedem o seu IP de saída?#

Na prática você encontra três formas.

Cadastro obrigatório. O serviço não libera o acesso enquanto o endereço não estiver cadastrado. Muitas vezes você não consegue fazer isso sozinho: abre um chamado no suporte e o endereço é digitado à mão do outro lado. Essa forma é comum em integrações com bancos e órgãos públicos e em algumas APIs de marketplace e de transporte. Em alguns serviços a regra vale para um único ambiente, por exemplo para o de teste e não para o de produção.

Restrição opcional. Quem ativa a restrição não é o serviço, é você. Muitos serviços de mensagens e de e-mail têm no painel um campo do tipo "aceitar requisições somente destes endereços". Nessa forma a causa do erro costuma ser uma configuração esquecida: você mesmo ativou a restrição, o servidor mudou e o endereço antigo ficou na lista.

O sentido inverso. Em fluxos como webhooks é o serviço que envia a requisição para você, e a lista de permitidos fica do seu lado: você adiciona ao próprio firewall os endereços que o serviço publica na documentação.

As duas primeiras formas costumam aparecer lado a lado em um mesmo provedor: o ambiente de teste exige autorização de IP e a produção não, e o painel ainda oferece uma restrição opcional que você mesmo liga. Muitos provedores de mensageria e de marketplace listam essa restrição como passo de segurança recomendado nos seus guias de preparação.

As regras variam de serviço para serviço e mudam com o tempo. Leia na documentação para desenvolvedores do próprio serviço em qual ambiente, para quantos endereços e por qual canal o acesso é liberado.

Quando aparece o aviso "autorização de IP necessária"?#

O aviso não tem uma forma única. Os serviços comunicam a mesma situação com códigos diferentes:

• Uma mensagem explícita. Um texto como "autorização de IP necessária" ou "IP not allowed" no corpo da resposta. É o caso mais fácil de diagnosticar.
• 403 Forbidden. O servidor entendeu a requisição, mas recusou. Como a página da MDN sobre o 403 também registra, com esse código reenviar as credenciais não muda o resultado.
• 401 Unauthorized. Alguns serviços comunicam um endereço que não confere com o mesmo código de um erro de credencial. Se você renovou a chave três vezes e continua recebendo 401, olhe o endereço.
• 503 ou tempo esgotado. Se o filtro acontece no firewall, antes da aplicação, pode não chegar nenhuma resposta útil. Alguns serviços documentam exatamente esse comportamento: um 503 no ambiente de teste que, na verdade, significa falta de autorização de IP.

O contrário também acontece: nem todo 403 é problema de endereço. Algumas APIs recusam com o mesmo 403 as requisições sem um cabeçalho obrigatório, como o User-Agent. Antes de trocar o endereço, leia o corpo da resposta e compare a sua requisição com o exemplo da documentação, cabeçalho por cabeçalho. A leitura geral dos códigos de status está em Códigos de status HTTP no web scraping.

Como descobrir o seu IP de saída?#

O endereço informado ao serviço não é o 192.168.x.x que aparece nas configurações de rede do computador; esse só vale na rede local. O que o serviço enxerga é o endereço público pelo qual o modem ou o servidor sai para a internet. Para achar o endereço certo:

1. Meça na máquina que envia a requisição. Se a integração roda em um servidor, descubra o endereço pelo terminal desse servidor, não pelo navegador do seu notebook.
2. Chame um serviço de eco. curl https://api.ipify.org ou curl https://checkip.amazonaws.com devolvem como resposta apenas o endereço que enxergam.
3. Meça pelo caminho que a aplicação usa. Se a aplicação sai por um proxy ou por uma VPN corporativa, meça pelo mesmo caminho; uma medição direta mostra outro endereço.
4. Confira o IPv6. curl https://api64.ipify.org devolve o seu endereço IPv6 se a linha tiver um. Se o domínio do serviço aceita IPv6, a requisição pode estar saindo por ali; nesse caso o endereço IPv4 informado nem chega a ser visto.
5. Repita a medição. Rode o mesmo comando depois de reiniciar o modem e mais uma vez no dia seguinte. Se o endereço muda, a linha é dinâmica.

Por que o IP cadastrado deixa de conferir?#

Você informou o endereço certo, funcionou por um tempo e depois parou. Causas possíveis:

• IP dinâmico. Na maioria das linhas residenciais e de pequenos escritórios o endereço pode mudar sempre que o modem reconecta ou quando a concessão expira. A distinção completa está em IP estático e IP dinâmico.
• CGNAT. Se a operadora divide o mesmo endereço público entre muitos assinantes, o endereço que você vê não é seu, e na próxima conexão você pode cair em outro endereço do pool. Cadastrar um endereço assim em uma API é abrir a porta também para outros assinantes do mesmo pool. Como identificar está em O que é CGNAT.
• Hotspot do celular ou VPN esquecida ligada. A conexão compartilhada pelo celular e o cliente de VPN esquecido no computador fazem a requisição sair por um endereço completamente diferente.
• Mais de um ponto de saída. Contêineres com escalonamento automático e funções serverless que não estão ligadas a uma rede privada podem sair, a cada execução, com um endereço diferente do amplo pool do provedor de nuvem. O endereço público atribuído automaticamente a um servidor na nuvem também muda, na maioria dos provedores, quando o servidor é parado e iniciado de novo; para que seja permanente é preciso reservar um endereço.

Quatro opções para um IP de saída fixo#

A solução duradoura é um endereço que você informa ao serviço uma única vez e que não muda. Há quatro caminhos; qual é o certo depende de onde o código roda e de quais dados ele transporta.

IP estático do provedor de internet. Nenhum sistema novo entra no caminho; o endereço da linha que você já tem é fixado. O endereço fica preso a essa linha; o desenvolvedor em home office ou a filial em outra cidade não conseguem sair por ele. Os passos do pedido estão na seção "Como conseguir um IP fixo?" do artigo irmão.

Servidor com IP fixo. Rodar um trabalho contínuo, como a sincronização noturna de estoque ou a busca de pedidos, em um servidor com endereço reservado, e não no computador do escritório, resolve ao mesmo tempo o problema do endereço e o da continuidade.

NAT gateway. Em vez de informar um endereço para cada máquina, você liga todas a uma única porta de saída. Segundo a documentação de NAT gateway da AWS, ao criar um NAT gateway público associa-se a ele um Elastic IP, e os recursos das sub-redes privadas saem para a internet por essa porta. A visão geral do Cloud NAT do Google Cloud também afirma que, quando os endereços NAT são atribuídos manualmente, eles podem ser compartilhados com a parte de destino, e cita como exemplo serviços que só aceitam conexões de endereços conhecidos.

Proxy estático. O cliente sai para a internet por um endereço de proxy dedicado a você e que não muda, e é esse endereço que você informa ao serviço. Não importa se a linha é dinâmica ou está atrás de CGNAT, porque o endereço que o serviço enxerga é o do proxy. Em troca, um terceiro entra no caminho do tráfego; onde isso é inaceitável está na próxima seção.

Por que não se usa proxy em integrações de pagamento, saúde e nota fiscal eletrônica?#

APIs de POS virtual e de instituições de pagamento, sistemas de autorização e registro de instituições de saúde, integrações de nota fiscal e escrituração eletrônicas e serviços de notificação de órgãos públicos formam uma classe à parte. Nessas integrações não recomendamos um proxy de terceiros como endereço de saída; isso inclui o nosso próprio produto. O caminho certo é o IP estático do provedor de internet, o endereço reservado do seu próprio servidor ou um NAT gateway na sua conta de nuvem. Os motivos:

1. O endereço cadastrado precisa ser seu. Essas instituições guardam o endereço não como uma configuração de segurança, e sim como um registro que diz "esta operação veio deste sistema desta empresa". O endereço de um proxy pertence ao provedor e, quando você deixa o serviço, pode ser entregue a outro cliente. Uma permissão que ninguém lembra de apagar do outro lado deixa o novo usuário do endereço um passo mais perto da sua conta.
2. A corrente ganha mais um elo. Em HTTPS o proxy não vê o conteúdo da requisição: a conexão é feita por um túnel CONNECT e a criptografia fica entre você e a API. Mesmo assim, o proxy vê para qual servidor você envia dados, quando e quanto, e em uma falha o fluxo de pagamento ou de notas para por causa de um sistema que você não controla.
3. Contrato e auditoria. Os contratos dessas integrações e as normas a que estão sujeitas esperam que você saiba e consiga documentar por quais sistemas os dados passam. Leia as especificações da instituição; muitas exigem de forma expressa que o endereço seja de uma linha ou de um servidor da sua empresa.
4. Não é necessário. Esses sistemas já pedem um servidor que rode sem interrupção. Se você tem servidor, tem endereço fixo.

O mesmo limite vale para qualquer integração que transporte dados pessoais: em uma linha por onde passam dados de identidade de clientes, de saúde ou de cartão, o ponto de saída deve ser a sua própria infraestrutura.

Em que casos o proxy estático serve?#

Sobram os casos que não transportam dados sensíveis e pedem solução rápida:

• Ambiente de teste e desenvolvimento. O serviço pede um endereço para o ambiente de teste, e os desenvolvedores trabalham de casa, em linhas dinâmicas. Em vez de contratar IP estático para a linha de cada um, a equipe sai por um único endereço de proxy, e é esse que se informa ao serviço.
• Equipe distribuída, um único endereço permitido. A equipe que usa a mesma ferramenta interna a partir de três cidades não precisa informar três endereços ao serviço.
• Período de transição. A integração precisa continuar funcionando até que o pedido de IP estático ou a migração para um servidor termine.
• Pequena empresa atrás de CGNAT. A linha funciona com endereço compartilhado e o provedor não oferece IP estático naquela assinatura.

Em todos os casos leia antes os termos de uso do serviço: se ele exige que as requisições venham direto da sua própria infraestrutura, o proxy deixa de ser opção.

Na escolha, observe duas propriedades. O endereço precisa ser dedicado a você: se você cadastra em uma API um endereço compartilhado, quem usa o mesmo endereço também passa por esse filtro. O endereço precisa ser estático; os endereços de um pool rotativo mudam por definição. O conceito está explicado em detalhes na nossa página de Proxies estáticos. Na Proxynet essa necessidade é atendida por Proxies ISP e Proxies de datacenter: nos dois o endereço é alocado só para você e não muda até você abrir mão dele. O preço base mensal é de R$ 5,2 para um endereço ISP e de R$ 3,6 para um endereço de datacenter. Para clientes de API um endereço de datacenter costuma bastar; se o serviço também restringe blocos de endereços de datacenter, escolha um endereço ISP.

Como configurar um único endereço de saída com proxy estático?#

1. Obtenha um endereço de proxy estático dedicado a você.

2. Meça o endereço de saída com o comando abaixo. Essa resposta é o endereço que você vai informar ao serviço; repita o comando com algumas horas de intervalo e confirme que o endereço continua o mesmo:

   bash

   curl -x http://user:pass@pr.proxynet.io:8000 https://api.ipify.org

3. Informe esse endereço ao provedor da API (campo no painel ou chamado no suporte). Dependendo do serviço, o cadastro pode levar minutos ou horas para valer; consulte o prazo na documentação do serviço.

4. Defina o proxy no cliente. Para o Postman, a tela de configuração está em Configuração de proxy no Postman; para a linha de comando, em Como usar cURL com proxy; para o código da aplicação, em Como usar proxy no Node.js, sempre passo a passo.

5. Chame sempre o endereço da API com https://. A conexão TLS dentro do túnel é feita diretamente com o servidor da API; a chave e os dados não chegam ao proxy em texto aberto.

Conferindo o IP de saída com código#

Se o endereço parece certo uma vez e depois muda, uma medição só engana. O script abaixo envia três rodadas de requisições a dois serviços de eco diferentes, abre uma conexão nova a cada medição e compara todos os endereços vistos com o que você informou ao serviço. Como ele termina com o código 1 quando há divergência, dá para incluí-lo no pipeline de deploy (CI). 203.0.113.10 é um endereço de exemplo reservado para documentação; troque pelo seu.

import sys
import time

import requests

PROXY_URL = "http://user:pass@pr.proxynet.io:8000"
EXPECTED_IP = "203.0.113.10"  # o endereço que você informou ao provedor da API
ECHO_URLS = ["https://api.ipify.org", "https://checkip.amazonaws.com"]
ROUNDS = 3


def egress_ip(url):
    # Cada medição abre uma sessão nova: se um túnel aberto for reutilizado,
    # um endereço de saída que muda passa despercebido.
    with requests.Session() as session:
        session.trust_env = False  # HTTP_PROXY / NO_PROXY do shell não devem interferir
        session.proxies = {"http": PROXY_URL, "https": PROXY_URL}
        response = session.get(url, timeout=15)
        response.raise_for_status()
        return response.text.strip()


def main():
    seen = set()
    for round_no in range(1, ROUNDS + 1):
        for url in ECHO_URLS:
            ip = egress_ip(url)
            seen.add(ip)
            print(f"rodada {round_no}  {url:<32} {ip}")
        time.sleep(2)

    if seen == {EXPECTED_IP}:
        print(f"OK: todas as requisições saíram por {EXPECTED_IP}")
        return 0
    print(f"DIVERGENTE: esperado {EXPECTED_IP}, vistos {sorted(seen)}")
    return 1


if __name__ == "__main__":
    sys.exit(main())

Rodamos o script por um proxy de teste local: cada uma das seis medições abriu o próprio túnel CONNECT, e o script terminou com 0 quando o endereço era o esperado e com 1 quando não era. Ao digitar a senha errada de propósito, o Requests lançou um ProxyError com 407; um erro de credencial não cai em silêncio para uma conexão direta. Se você não usa proxy (linha ou servidor com IP estático), basta apagar a linha session.proxies; o script passa a conferir o endereço de saída da própria máquina.

No Node.js a mesma conferência pode ser feita sem instalar pacote adicional. Nas versões atuais do Node.js, o fetch nativo lê a variável HTTPS_PROXY quando NODE_USE_ENV_PROXY=1 está definido (os detalhes estão no nosso artigo de Node.js):

const EXPECTED_IP = process.env.EXPECTED_IP ?? "203.0.113.10";
const ECHO_URLS = ["https://api.ipify.org", "https://checkip.amazonaws.com"];

const seen = new Set();
for (const url of ECHO_URLS) {
  const response = await fetch(url, { signal: AbortSignal.timeout(15_000) });
  if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`);
  const ip = (await response.text()).trim();
  seen.add(ip);
  console.log(url.padEnd(32), ip);
}

const ok = seen.size === 1 && seen.has(EXPECTED_IP);
console.log(ok ? `OK: ${EXPECTED_IP}` : `DIVERGENTE: esperado ${EXPECTED_IP}, vistos ${[...seen].join(", ")}`);
process.exitCode = ok ? 0 : 1;

NODE_USE_ENV_PROXY=1 HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000" node check-egress-ip.mjs

Casos de uso#

• Teste de integração com marketplace: O ambiente de teste pede um endereço e a equipe trabalha distribuída. A equipe sai por um único endereço estático; ao passar para produção, leia de novo a regra do serviço para esse ambiente. Outros cenários de comércio eletrônico estão na nossa página de proxy para e-commerce.
• Testar respostas de API que dependem da localização: Para ver como o mesmo endpoint responde a partir de países diferentes, usam-se endereços fixos com país selecionável; a montagem está na nossa página de teste de aplicativos.
• APIs de transporte, estoque e fornecedores: Se o depósito, a contabilidade e a equipe de operações em home office acessam o mesmo serviço, ou todos se conectam por VPN à rede do escritório ou saem por um único endereço estático.

Se o IP está certo e o erro continua#

• O cadastro ainda não está ativo. Se você informou o endereço hoje, aguarde o prazo de processamento do serviço.
• Ambiente errado. O endereço cadastrado no ambiente de teste não vale em produção, e a chave de produção não vale no ambiente de teste. Confira o domínio e o par de chaves juntos.
• Você está saindo por IPv6. Se api64.ipify.org devolve um endereço IPv6 e o serviço aceita IPv6, informe também o endereço IPv6 ou force o cliente a usar IPv4 (curl -4).
• Cabeçalho ausente. A falta de User-Agent, de Content-Type ou de um cabeçalho próprio do serviço também pode devolver 403. Rode a requisição de exemplo da documentação exatamente como está e ache a diferença.
• A requisição não sai da máquina que você imagina. O serviço pode ter cadastrado o endereço do servidor enquanto você testa a requisição no seu computador, pelo Postman; a tarefa agendada também pode estar rodando em outro servidor. Rode o script ao lado do processo que envia a requisição.
• Variável de proxy no shell. A ferramenta iniciada em um terminal com HTTPS_PROXY definido sai pelo proxy sem você perceber; já a aplicação iniciada como serviço não enxerga a variável do shell.

Guia de decisão#

Perguntas frequentes#

O que significa "autorização de IP necessária"?#

Significa que o serviço comparou o endereço de onde veio a requisição com os endereços cadastrados na sua conta e não achou correspondência. A chave de API pode estar correta; o problema está no endereço por onde a requisição saiu. Meça o IP de saída na máquina que envia a requisição e compare com o endereço cadastrado.

Dá para integrar uma API usando IP dinâmico?#

Se o serviço não pede endereço, sim, sem nenhum problema. Se pede, a linha dinâmica não é solução duradoura: a cada mudança de endereço você precisa avisar o serviço de novo, e nesse intervalo a integração para. Consiga um endereço de saída fixo por uma das quatro opções.

É possível cadastrar mais de um endereço IP em uma API?#

Depende do serviço. Alguns aceitam vários endereços ou uma faixa, outros limitam a um só. Se você tem dois pontos de saída (o servidor e o reserva), informe os dois no mesmo pedido.

Dá para ter IP fixo com VPN?#

Com aplicativos de VPN para consumidores, não: os endereços são compartilhados por muitos usuários e podem mudar a cada conexão. Já o servidor VPN da própria empresa funciona, porque o endereço de saída dele é fixo e os funcionários remotos saem pela rede do escritório.

Se eu usar proxy estático, o proxy vê a minha chave de API?#

Se você chama a API com https://, não. O proxy só vê o nome e a porta do servidor ao qual você quer se conectar e depois repassa o túnel criptografado; a chave e as respostas ficam dentro do túnel. Em uma API chamada por http:// tudo trafega em texto aberto; não use uma API assim, com ou sem proxy.

O que fazer com o cadastro do IP na API quando eu deixar o proxy?#

Peça a remoção no mesmo dia. Mesmo que o endereço fosse dedicado a você, ele pode ser entregue a outro cliente depois do fim do serviço, e enquanto o cadastro existir esse endereço continua permitido para a sua conta. A mesma regra vale para os endereços reservados de servidores que você desliga.

Em resumo#

O erro de autorização de IP não é um erro de código, e sim um endereço que não confere: o serviço reconhece um endereço e a requisição sai de outro. Primeiro meça o IP de saída na máquina que envia a requisição, depois fixe o endereço. Em integrações que transportam dados sensíveis, esse endereço deve ser o IP estático da sua própria linha, o seu próprio servidor ou um NAT gateway na sua conta de nuvem; em pagamento, saúde e nota fiscal eletrônica, não coloque um terceiro no meio. Para ambientes de teste, equipes distribuídas e períodos de transição, um endereço estático dedicado a você é suficiente; as opções estão em nossos serviços de proxy.