Saltar para o conteúdo principal
Quando um agente é sequestrado — injeção de prompt, um resultado de ferramenta envenenado, um loop descontrolado — o que ele pode de fato fazer é limitado por exatamente uma coisa: o que sua chave de API tinha permissão de fazer. Uma chave sem limites e sem política transforma um agente comprometido em um incidente que abrange todo o workspace. Esta página é o processo de endurecimento que você roda contra cada chave antes de colocá-la no ar, e novamente em uma cadência depois. Ela é deliberadamente curta: uma checklist, um exemplo trabalhado, depois links para a profundidade de cada campo. Para o modelo mental por trás dela, comece com Escopo & chaves; para a referência campo a campo, veja a visão geral de chaves.

​
1. A checklist de menor agência

Passe cada chave — nova ou existente — por estes seis portões no editor de chaves (/console/token). Definir qualquer um deles exige o papel de Developer ou superior; os dois planos de política (§5–6) são criados separadamente e vinculados aqui.
Defina model_limits para a lista exata que este agente precisa (e habilite model_limits_enabled). Uma chamada a qualquer modelo fora da lista é rejeitada antes de sair do gateway, então um agente sequestrado não pode escalar para um modelo mais caro ou mais capaz. Verifique: a lista é tão curta quanto o trabalho permite — idealmente um modelo? Profundidade: Limites de modelo.
Defina allow_ips para os endereços de origem ou CIDR de onde o agente de fato chama. Uma chave vazada apresentada de qualquer outro lugar é rejeitada na camada de auth. Vazio significa que todos os IPs são permitidos. Verifique: para um agente de host fixo ou agendado, a lista é não-vazia e escopada para aquele egress? Profundidade: Lista de permissão de IP.
Defina credit_limit_usd para um teto que o agente nunca deveria cruzar em sua vida. O gateway o aplica contra o gasto da chave. 0 significa ilimitado — um loop descontrolado pode drenar todo o seu saldo. Verifique: o limite é um orçamento real, não 0? Profundidade: Cota, limite & expiração.
Defina expired_time para uma expiração absoluta — o fim do sprint, do deployment ou do run de CI. -1 significa nunca expira. Uma chave de curta duração não pode persistir como superfície de ataque esquecida. Verifique: uma chave efêmera ou de contratado tem uma expiração real, não -1? Profundidade: Chaves expiráveis.
Anexe um guardrail via guardrail_id para que o texto da requisição (e, onde suportado, da resposta) seja filtrado em busca de PII, segredos e intenção de injeção antes de chegar ao modelo. Verifique: uma chave que lida com prompts sensíveis tem um guardrail vinculado, ou herda um padrão de workspace? Veja §5.
Anexe uma política de firewall via firewall_policy_id para que cada chamada de ferramenta, dispatch de MCP e egress que esta chave emite seja avaliada contra uma lista de permissão do que o agente legitimamente precisa. Verifique: um agente que chama ferramentas tem uma política de firewall vinculada, ou herda o padrão do workspace? Veja §6.
Os campos acima são as únicas alavancas configuráveis pelo cliente em uma chave — defina todas no console; nada aqui exige uma mudança no código do agente. Reler uma chave a mostra mascarada; o plaintext é mostrado uma vez na criação. Veja Mascaramento de chave.

​
2. O quê / com que frequência / onde

Três perguntas transformam a checklist de uma tarefa única em uma postura.

O quê

Os seis portões acima, em ordem: model_limits → allow_ips → credit_limit_usd → expired_time → guardrail_id → firewall_policy_id.

Com que frequência

Em cada chave na criação, e em uma revisão recorrente — quando o escopo de um agente muda, quando você rotaciona uma chave, e em uma cadência fixa para chaves de longa duração.

Onde

No editor de chaves do console (/console/token), como um Developer+. As duas políticas são criadas em seus próprios consoles, depois vinculadas na chave.

​
3. Uma chave de menor agência concreta

Um agente agendado que resume tickets de suporte com um modelo barato, a partir de um único host, quase não precisa de agência. Uma chave totalmente endurecida:
CampoValorPor quê
model_limitsum modelo de sumarizaçãonão pode escalar para um modelo de fronteira
allow_ipso CIDR de egress do agendadoruma chave vazada é inútil em outro lugar
credit_limit_usdum teto semanalum loop descontrolado não pode drenar o saldo
expired_timefim do deploymentautoexpira, não pode persistir
guardrail_idum guardrail de mascaramento de PIIo texto da requisição é filtrado
firewall_policy_idpermite por lista apenas suas ferramentasnenhuma chamada de ferramenta surpresa
Se este agente for sequestrado, ele ainda só pode chamar um modelo, só a partir de um intervalo de IP, só até seu limite, e só as ferramentas que sua política de firewall permite. O resto do workspace fica intocado — e a trilha de auditoria do firewall mostra exatamente o que ele estava autorizado a fazer.
Uma chave sem model_limits, sem allow_ips, credit_limit_usd: 0, expired_time: -1 e sem anexo de política tem agência máxima. Se ela vazar, o portador obtém seu workspace inteiro. Trate essa combinação como um achado, não como um padrão — veja ilimitada vs limitada.

​
4. A chamada de relay /v1 vs o console

A checklist é configurada no console com sua sessão (um usuário Developer+). Seu agente nunca toca essas rotas de config — ele apresenta sua chave de relay com escopo (sk-orca-…) nas chamadas de inferência /v1/*, e os limites e políticas vinculadas acima são aplicados em cada uma. 
# A chamada em runtime do agente — a chave de relay, escopada pela checklist acima.
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..."}]
  }'
Se o model_limits da chave não inclui openai/gpt-4o-mini, esta chamada é rejeitada antes de sair do gateway. Se o IP do chamador não está em allow_ips, ela é rejeitada na camada de auth. O código do agente permanece o mesmo; a chave decide o raio de explosão.

​
5. Portão 5 — o guardrail vinculado

guardrail_id vincula uma política de conteúdo ordenada e com escopo de workspace à chave. A resolução é o guardrail explícito da chave (se ele existe e está habilitado), senão o padrão do workspace, senão nenhum.
Os guardrails são um interruptor de desligar estrito quando desabilitados: um guardrail_id desabilitado ou deletado significa que a chave não recebe nenhum guardrail — ela não cai de volta para o padrão do workspace. Isto é o oposto do plano de firewall (§6), então verifique que o guardrail vinculado está habilitado, não apenas anexado.
As regras de um guardrail rodam antes do modelo (estágio de input) e, onde suportado, na resposta (estágio de output), com ações block, mask ou flag. O preset PII Shield, por exemplo, mascara PII na requisição antes de ela sequer chegar ao modelo. Crie e anexe guardrails como Developer+ — veja Guardrails e Vincular políticas.

​
6. Portão 6 — a política de firewall vinculada + escopo de gateway

firewall_policy_id vincula uma política de chamada de ferramenta com escopo de workspace. Ela governa as ações que um agente toma — ferramentas anunciadas, tool_calls emitidos pelo modelo, dispatches de MCP e egress outbound — contra uma lista de regras ordenada cujos vereditos são allow, audit, deny, sanitize, pending_approval ou cap_cost.
O plano de firewall resolve diferentemente dos guardrails: uma política de firewall anexada desabilitada cai de volta para o padrão do workspace, ela não desliga o enforcement. Então vincular uma política e desabilitá-la reverte a chave ao padrão do workspace — ela nunca fica silenciosamente desprotegida.
A maneira mais rápida de definir ambos os planos de uma vez é um nível de autonomia — um único interruptor que configura atomicamente a postura de firewall e de guardrail do seu workspace (tight / balanced / permissive), com desfazer em um clique. Veja Firewall §8.
is_firewall_gateway é um tipo separado de chave — cunhada apenas para o MCP do Firewall e as rotas de evaluate-hook (/api/v1/firewall/*), nunca para inferência. Uma chave normal recebe 403 nessas rotas, e uma chave de gateway no caminho de inferência está super-escopada. Habilitar a flag, e ler o plaintext de uma chave de gateway, exige Admin+. Uma chave, um propósito.

​
7. Após a checklist

Linha de base de agentes seguros

A postura inicial recomendada — um interruptor de autonomia, depois ajuste a partir do tráfego real.

Vincular políticas

Como guardrail_id e firewall_policy_id se anexam e resolvem.

Agência excessiva

A ameaça que esta checklist foi feita para conter.

Chave vazada

O que fazer no momento em que uma chave com escopo é exposta.
Quanto mais estreita cada chave, menor o raio de explosão se qualquer agente for comprometido — e mais claro o registro do que cada agente estava autorizado a fazer. Rode a checklist de menor agência em cada chave, e continue rodando-a.