Saltar para o conteúdo principal
Uma chave sem restrição de origem é uma credencial portadora pura: quem segura a string pode apresentá-la de qualquer lugar. O campo allow_ips transforma uma chave em uma chave de api com ip whitelist — ela só funciona quando apresentada de um endereço de origem que você listou. Uma chave vazada reproduzida da máquina de um atacante, de um proxy residencial ou de um runner de CI comprometido é rejeitada antes de tocar um modelo. Esta é a metade de vínculo de origem da menor agência: model_limits limita quais modelos uma chave pode alcançar, e allow_ips limita de onde a chave pode ser apresentada.

​
1. O que allow_ips faz

allow_ips mantém uma lista de endereços de origem ou faixas CIDR. Em cada requisição, o OrcaRouter compara o IP de origem do chamador com essa lista:
  • Correspondência → a requisição prossegue para as verificações de limite de modelo, cota e política.
  • Sem correspondência → a requisição é rejeitada na camada de auth com HTTP 403 (access_denied), antes de qualquer chamada de modelo upstream.
  • Lista vazia → sem restrição; a chave é aceita de qualquer endereço.
A verificação é o primeiro portão que uma chave passa, junto com a validade da chave — ela roda antes dos guardrails, antes do firewall, antes da medição. Uma origem não listada nunca chega às suas políticas ou ao seu saldo.
Um allow_ips vazio significa todos os IPs permitidos, não nenhum. Deixá-lo em branco é o padrão irrestrito — fixe a chave para fazer o campo fazer qualquer coisa.

​
2. Formatos aceitos

Cada entrada é um único IP ou uma faixa CIDR. Misture ambos livremente; liste uma entrada por linha.

Endereço único

203.0.113.7 — exatamente um host. Melhor para um servidor de IP fixo ou um gateway NAT com um endereço de egress estável.

Faixa CIDR

203.0.113.0/24 — um bloco inteiro. Melhor para uma sub-rede de cloud, um pool de VPN ou um grupo de autoscaling atrás de um CIDR de egress.
Um IP puro corresponde àquele único endereço; um CIDR corresponde a cada endereço no bloco. Tanto literais IPv4 quanto IPv6 são parseados.
Fixe na faixa mais estreita que ainda cobre todo chamador legítimo. Um host (/32) é mais apertado que um /24; um /24 é mais apertado que “qualquer lugar”. Cada bit que você descarta amplia o conjunto de lugares onde uma chave vazada ainda funciona.

​
3. Definir no console

Defina allow_ips no editor de chave em /console/token. Criar ou editar uma chave exige o papel de Developer ou superior.
  1. Abra Console → API Keys e crie ou edite uma chave.
  2. No editor de chave, insira os seus endereços confiáveis no campo IP allow-list — um IP ou CIDR por linha.
  3. Salve. A restrição se aplica na próxima requisição que a chave faz — sem redeploy, sem mudança no código do agente.
Verifique o endereço de origem real que o gateway vê antes de travar uma chave. Se o seu agente fica atrás de um NAT, de um load balancer ou de um proxy de egress, o endereço que o OrcaRouter observa é esse hop de egress — não o IP privado do agente. Faça allow-list do endereço de egress, e teste a partir do ambiente deployado antes de entrar em produção.

​
4. Um exemplo concreto: um agente agendado

Um job agendado que resume tickets roda apenas de uma sub-rede de cloud. Fixe a sua chave a essa sub-rede para que a credencial seja inútil em qualquer outro lugar.
CampoValorEfeito
allow_ips203.0.113.0/24só o bloco de egress do scheduler pode apresentar esta chave
model_limitsum modelo de sumarizaçãonão pode escalar para um modelo de fronteira
credit_limit_usdum teto semanalum loop descontrolado não pode drenar o saldo
A própria chamada de relay não muda — ela ainda usa a chave sk-orca-… como um token portador: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Summarize this ticket..."}]
  }'
Apresentada de dentro de 203.0.113.0/24, a chamada prossegue. Reproduza exatamente a mesma requisição de qualquer outro endereço e o gateway retorna: 
{
  "error": {
    "message": "您的 IP 不在令牌允许访问的列表中 (request id: ...)",
    "type": "orcarouter_api_error",
    "code": "access_denied"
  }
}
O modelo nunca é chamado, nenhuma cota é gasta, e a rejeição é registrada.
allow_ips é configurado inteiramente através do editor de chave do console — uma ação de Developer-ou-acima na sua sessão de workspace. Não há self-service por chave de relay para isso: uma chave não pode ampliar a sua própria allow-list de origem.

​
5. O que uma allow-list de IP contém e não contém

Uma chave de api com ip whitelist delimita onde uma chave funciona — uma fatia do raio de explosão. Ela compõe com os outros campos de escopo em vez de substituí-los.
Uma credencial exfiltrada de logs, de um commit git ou de um laptop violado é peso morto a menos que o atacante também consiga originar tráfego da sua faixa em allow-list. Este é o trabalho central do campo — veja chave vazada para a resposta a incidente completa.
Se o comprometimento é um host em allow-list — uma dependência envenenada rodando no seu próprio servidor — a verificação de IP de origem passa. Combine allow_ips com model_limits, um limite de gasto e uma política de firewall para que um comprometimento de origem confiável ainda seja delimitado.
Uma fixação de IP não torna uma chave de vida curta. Combine-a com uma expiração absoluta e um cronograma de rotação para que uma chave tanto pare de funcionar de novos lugares quanto pare de funcionar eventualmente.

​
6. Notas operacionais

Se os seus chamadores não têm um endereço de origem estável (serverless com egress rotativo, clientes mobile, redes de escritório amplas), uma fixação de IP é o controle errado — você ou trancaria fora tráfego real ou ampliaria a faixa até que ela fique sem sentido. Apoie-se em model_limits, limites de gasto, expiração e anexos de política em vez disso.
Editar allow_ips entra em vigor na próxima requisição — não há atraso de propagação para esperar. Quando você adiciona uma região ou migra uma sub-rede, atualize a chave primeiro, confirme que a nova faixa funciona, depois descarte a antiga.
allow_ips vive na chave individual, então cada agente pode ter o seu próprio vínculo de origem. Uma chave de scheduler pode fixar a uma sub-rede de batch enquanto uma chave interativa permite uma faixa de escritório mais ampla — ambas no mesmo workspace.

​
7. Próximos passos

O objeto token

Cada campo em uma chave, incluindo allow_ips, em uma referência.

Limites de modelo

Limite quais modelos uma chave pode alcançar — a outra metade do vínculo de origem + escopo.

Chave vazada

O que fazer no momento em que uma chave é exposta.

Checklist de menor agência

Passe cada chave pela mesma passada de hardening.
Uma allow-list de IP é o corte de raio de explosão mais barato que você pode fazer: um campo, sem mudança de código, e uma chave vazada para de funcionar de todos os lugares onde não deveria rodar. Combine-a com o resto do modelo de chave com escopo para defesa em profundidade.