1. Por que chaves de api com escopo para agentes de llm
Uma chave de API geral é uma credencial portadora: quem a possui pode chamar qualquer modelo, de qualquer lugar, por qualquer valor, sem nenhuma política anexada. Isso é o oposto do que um agente autônomo precisa. No OrcaRouter, uma chave de API não é apenas uma credencial — é uma declaração de escopo. Cada chave carrega suas próprias restrições (quais modelos, quais IPs, quanto gasto, quando expira) e aponta para o guardrail e a política de firewall que governam o seu tráfego. Editar a política para a qual uma chave aponta entra em vigor na próxima requisição, sem redeploy e sem mudança no código do agente. O princípio é a menor agência: dê a cada agente a identidade mais estreita que ainda permita que ele faça o seu trabalho, e nada mais. Uma chave, um agente, um propósito.2. O que uma chave com escopo carrega
Cada chave é um pacote de limites mais dois anexos de política. Cada campo é documentado em sua própria página — os links dos spokes abaixo vão para a profundidade.Limites de modelo
model_limits restringe uma chave a uma lista nomeada de modelos. Uma
chamada fora da lista é rejeitada antes de deixar o gateway — o agente não
pode trocar para um modelo mais caro ou mais capaz.Lista de permissão de IP
allow_ips fixa uma chave a endereços de origem específicos. Uma chave
vazada apresentada de qualquer outro lugar é rejeitada na camada de auth.Cota, limite e expiração
credit_limit_usd limita o gasto vitalício (0 = ilimitado);
expired_time define uma expiração absoluta (-1 = nunca).Ambientes
environment é um rótulo livre (prod, staging, dev) para organizar
chaves e filtrar logs.Vincular políticas
guardrail_id e firewall_policy_id anexam uma política de conteúdo e uma
política de chamada de ferramenta à chave. Nenhum anexo cai de volta para o
padrão do workspace.O objeto token
A referência completa campo a campo de uma chave, incluindo
remain_quota / used_quota e is_firewall_gateway.Delimitada vs. ilimitada. Uma chave com
credit_limit_usd: 0 e
expired_time: -1 não tem limite de gasto e nunca expira — conveniente, mas o
pior raio de explosão se vazar. Veja
ilimitada vs. delimitada para quando
cada uma é apropriada.3. Uma chave concreta de menor agência
Um agente agendado que resume tickets de suporte com um modelo barato e roda de um único host precisa de quase nenhuma agência. Uma chave bem delimitada para ele:| Campo | Valor | Por quê |
|---|---|---|
model_limits | um modelo de sumarização | não pode escalar para um modelo de fronteira |
allow_ips | o CIDR de egress do scheduler | uma chave vazada é inútil em outro lugar |
credit_limit_usd | um teto semanal | um loop descontrolado não pode drenar o saldo |
expired_time | fim do deployment | auto-expira, não pode persistir |
guardrail_id | um guardrail de mascaramento de PII | o texto da requisição é triado |
firewall_policy_id | allow-list só das ferramentas que precisa | sem chamadas de ferramenta surpresa |
4. Vinculando os dois planos de política
Os dois anexos são os campos mais poderosos de uma chave, e eles resolvem de forma diferente quando uma política anexada está desabilitada:guardrail_id — triagem de conteúdo
guardrail_id — triagem de conteúdo
Triaga o texto da requisição e da resposta (PII, segredos, injeção de
prompt) contra um guardrail ordenado e com escopo
de workspace. Resolução: um
guardrail_id explícito e habilitado se
aplica; um desabilitado é o interruptor de desligar — ele não cai de
volta para o padrão do workspace. Sem anexo, o guardrail padrão do workspace
se aplica, senão nada.firewall_policy_id — enforcement de chamada de ferramenta
firewall_policy_id — enforcement de chamada de ferramenta
Governa as ações que um agente toma — chamadas de ferramenta,
dispatches de MCP, egress — contra uma política de firewall
com escopo de workspace. A resolução difere dos guardrails: uma política de
firewall anexada e desabilitada cai de volta para o padrão do
workspace, ela não desliga o enforcement.
is_firewall_gateway — um tipo diferente de chave
is_firewall_gateway — um tipo diferente de chave
Um token com escopo de gateway é cunhado apenas para as rotas do Firewall
MCP e de evaluate-hook (
/api/v1/firewall/*), nunca para inferência. Uma
chave regular recebe 403 ali. Habilitar essa flag, e ler o texto plano da
chave de gateway, exige Admin+.5. A seção de chaves
Gerenciar chaves
Crie, edite e revogue chaves no console.
Rotação
Rotacione uma chave sem downtime.
Chaves que expiram
Chaves de vida curta para agentes efêmeros e runs de CI.
Mascaramento de chave
As chaves são mascaradas na exibição; o texto plano é mostrado uma vez na
criação.
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.
6. Onde as chaves ficam na pilha de controle
Uma chave com escopo é a primeira camada de defesa — ela decide quem é o chamador e o que ele pode alcançar antes que qualquer política rode. Os guardrails e o Firewall são as camadas seguintes.Segurança de agentes de IA
Por que a identidade do agente é a fundação da pilha de controle.
Guardrails vs. Firewall
Os dois planos de política aos quais uma chave pode se vincular.
Agência excessiva
A ameaça que as chaves de menor agência são construídas para conter.