1. Os três escopos
Três conceitos se aninham um dentro do outro:- Workspace — o limite de tenant. Cada membro de um workspace compartilha o mesmo catálogo de guardrails e políticas de firewall. Nada cruza fronteiras de workspace — uma política criada no workspace A é invisível para o workspace B.
- Política — um conjunto de regras nomeado e com escopo de workspace (guardrail ou política de firewall). Editar uma política entra em vigor em cada chave conectada a ela na próxima requisição, sem redeploy.
- Chave — identidade mais vinculações. Uma chave carrega suas próprias restrições e aponta para as políticas que a governam.
2. O que uma chave carrega
Cada chave de API é um conjunto de limites e vinculações. Defina-os no editor de chave (/console/token) — criar ou editar chaves exige o papel de
Developer ou superior.
| Campo | O que restringe | Papel mínimo para definir |
|---|---|---|
model_limits | Restringe a chave a uma lista específica de modelos — qualquer chamada fora dessa lista é rejeitada antes de sair do gateway. | Developer |
allow_ips | Lista de permissão de IPs. Requisições de qualquer endereço não listado são rejeitadas na camada de autenticação. Vazio significa que todos os IPs são permitidos. | Developer |
credit_limit_usd | Limite de gasto em USD. 0 significa ilimitado. O gateway aplica isso contra o gasto vitalício da chave. | Developer |
expired_time | Timestamp de expiração absoluto. -1 significa que a chave nunca expira. | Developer |
environment | Um rótulo de formato livre (ex.: prod, staging, dev) para organizar chaves e filtrar logs. | Developer |
guardrail_id | Conecta um guardrail específico a esta chave. Cada chamada que esta chave faz é inspecionada por esse guardrail. | Developer |
firewall_policy_id | Conecta uma política de firewall específica a esta chave. Cada chamada de ferramenta que esta chave emite é avaliada por essa política. | Developer |
is_firewall_gateway | Marca a chave como um token com escopo de gateway — necessário para chamar as rotas de dispatch MCP e hook de avaliação. Uma chave regular recebe 403 nessas rotas. Ler o texto simples de uma chave de gateway exige Admin. | Admin (para habilitar e ler texto simples) |
3. Ordem de resolução de política
Para qualquer requisição, o OrcaRouter resolve o guardrail ativo e a política de firewall independentemente:- Vinculação da chave — se a chave tem um
guardrail_id(oufirewall_policy_id) explícito e essa política existe e está habilitada, ela se aplica. - Padrão do workspace — se a chave não tem vinculação, o guardrail (ou
política)
is_defaulthabilitado do workspace se aplica. - Sem enforcement — se nenhum for definido, a requisição passa sem inspeção de conteúdo ou enforcement de chamadas de ferramenta.
Os dois planos diferem quando uma política vinculada está desabilitada:
- Uma vinculação de guardrail desabilitada ou excluída significa que a chave não recebe nenhum guardrail — desabilitá-la é o interruptor de desligar; ela não cai de volta para o padrão do workspace.
- Uma vinculação de firewall desabilitada cai de volta para a política de firewall padrão do workspace — então desabilitar uma vinculação de firewall reverte a chave para o padrão do workspace, não desliga o enforcement.
0/não definida) sempre cai de volta para o padrão
do workspace; nenhum definido significa sem enforcement.4. Chaves de menor agência — uma chave por agente
A configuração mais segura é dar a cada agente sua própria chave com escopo restrito em vez de compartilhar uma única chave de workspace entre todos os chamadores. Uma chave bem escopada para um agente que só chama um modelo e executa tarefas agendadas pode parecer com:model_limits:["openai/gpt-4o-mini"]— o agente não pode mudar para um modelo mais caro ou mais capaz.allow_ips: o CIDR de egress do agendador — nenhuma outra fonte pode apresentar esta chave.credit_limit_usd: um teto de orçamento semanal — um loop descontrolado não pode esgotar o saldo do workspace.expired_time: o fim do sprint ou ciclo de deployment — a chave expira automaticamente e não pode ser reutilizada.guardrail_id: um guardrail específico para a sensibilidade de dados deste agente — mais restrito que o padrão do workspace.firewall_policy_id: uma política que apenas lista as ferramentas que este agente legitimamente precisa.
Crie chaves com escopo de gateway (
is_firewall_gateway) apenas para a
superfície de dispatch MCP ou hook de avaliação — nunca para tráfego de
inferência geral. Uma chave de gateway no caminho de inferência dá ao chamador
acesso às rotas /api/v1/firewall/*, que é uma capacidade mais ampla do que
ele precisa. Uma chave, um propósito.5. Onde as políticas são criadas
Guardrails e políticas de firewall têm ambos escopo de workspace e são compartilhados entre todos os membros, mas mudanças exigem o papel correto:- Ler qualquer guardrail, política ou chave — qualquer membro do workspace.
- Criar ou alterar guardrails, políticas de firewall, servidores MCP, níveis de autonomia, ações de aprovação e chaves de API comuns — Developer+.
- Habilitar
is_firewall_gatewayem uma chave; ler o texto simples de uma chave de gateway — Admin+.
6. Próximos passos
Linha de base de Agentes Seguros
A postura inicial recomendada — um interruptor de nível de autonomia,
depois ajuste a partir do tráfego real.
Obtenha uma chave de API
Crie sua primeira chave e conecte um guardrail ou política de firewall
no console.