Saltar para o conteúdo principal
Para rodar chamadas de ferramenta através do agent firewall de fora do relay de modelo — seu próprio loop de agente chamando o hook evaluate, ou um cliente MCP conectando ao gateway MCP — você autentica com uma chave dedicada com escopo de firewall-gateway, não uma chave de relay sk-orca-… comum. Uma chave normal recebe 403 nas rotas de gateway do firewall autenticadas por token (o callback de aprovação é a única exceção — ele é assinado por HMAC, não controlado por token). Esta página cobre o que é uma chave de api de gateway do firewall, como cunhar uma, e por que o escopo é restrito a Admin+. Para o motor em si, veja a Visão geral do Firewall e a referência profunda em Firewall.

​
1. O que é uma chave de api de gateway do firewall

Cada token (chave de API) no seu workspace carrega uma flag is_firewall_gateway. Quando ela é true, a chave tem permissão de alcançar a superfície de gateway do firewall:
RotaO que ela faz
POST /api/v1/firewall/evaluateVeredito pré-dispatch para uma chamada de ferramenta.
POST /api/v1/firewall/evaluate_planVerificação pré-execução para um plano de múltiplos passos.
ANY /api/v1/firewall/mcpO endpoint unificado do gateway MCP.
GET /api/v1/firewall/mcp_serversEnumera os servidores MCP registrados do workspace (retorna a auth upstream descriptografada).
GET /api/v1/firewall/approvals/:idConsulta o estado de aprovação de uma chamada retida.
Uma chave com is_firewall_gateway = false (o padrão) é uma chave de relay normal — ela serve o tráfego de modelo /v1/* e, se você vinculou uma política via firewall_policy_id, suas chamadas de ferramenta são governadas inline. Mas ela não pode chamar as rotas de gateway acima.
Duas chaves diferentes, dois trabalhos diferentes. Sua chave de relay (firewall_policy_id vinculado) é o que seu agente usa para falar com os modelos — o firewall governa suas chamadas de ferramenta automaticamente. Uma chave de gateway do firewall é o que o runtime do seu agente usa para pedir ao firewall um veredito diretamente, ou para fazer proxy de tools/call MCP através do gateway. A maioria dos workspaces só precisa de uma chave de gateway uma vez que adotam o hook evaluate ou o gateway MCP.

​
2. Por que uma chave normal recebe 403

O escopo de gateway desbloqueia duas capacidades sensíveis a segredos, então é deliberadamente isolado de chaves comuns:
  • /evaluate aceita um request_id fornecido pelo chamador que flui para o evento de firewall e os registros de aprovação. Qualquer chave de modelo poder forjar eventos de auditoria ou sondar silenciosamente resultados de política minaria a trilha.
  • /mcp_servers retorna credenciais upstream descriptografadas para que o proxy do SDK possa despachar para seus servidores MCP registrados. Isso é uma leitura de credencial, não uma chamada de modelo.
Por causa disso, o handler verifica a flag is_firewall_gateway do token apresentado e retorna HTTP 403 quando ela está ausente: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Não reutilize uma chave de relay de alto tráfego como chave de gateway, e não reutilize uma chave de gateway para tráfego de relay. Mantenha a chave do plano de ação separada para que seu raio de explosão e rotação sejam independentes das suas chaves de modelo.

​
3. Cunhe uma — restrita por papel a Admin+

Definir is_firewall_gateway = true exige Admin do workspace ou acima. Um Developer pode criar e editar chaves comuns, mas não pode cunhar uma com escopo de gateway — a flag é uma preocupação de gerenciamento de segredos, então ela fica acima do papel normal de escrita de token. Você configura chaves no console, sob as chaves de API do seu workspace. Para cunhar uma chave de gateway:
1

Abra as chaves de API como um Admin

Faça login como um Admin do workspace (ou superior) e abra a página de chaves de API no console.
2

Crie uma chave com o escopo de gateway

Crie uma nova chave e habilite seu escopo de firewall gateway (is_firewall_gateway). Uma sessão de papel Developer não verá o escopo entrar em vigor — o servidor mantém a flag false para não-admins.
3

Copie a chave uma vez

Copie o valor completo da chave na criação. Depois disso o console a mascara na exibição, e ler o texto plano de uma chave de gateway de volta é ele mesmo Admin+ — não-admins têm as linhas de gateway omitidas de uma resposta de “buscar minhas chaves”.
Baixar a flag é mais permissivo que levantá-la: limpar is_firewall_gateway (rebaixar uma chave de gateway de volta para uma chave normal) é aberto a qualquer papel que possa editar a chave. Apenas levantá-la para true é Admin+.

​
Controles de papel em resumo

AçãoPapel
Criar/editar uma chave comumDeveloper+
Definir is_firewall_gateway = trueAdmin+
Ler o texto plano de uma chave de gateway de voltaAdmin+
Limpar is_firewall_gateway (rebaixar)qualquer editor de chave

​
4. Um exemplo concreto

Você está rodando um loop de agente e quer verificar uma chamada de ferramenta antes de despachá-la. Como um Admin, cunhe uma chave de gateway no console, depois chame o hook evaluate a partir do seu runtime com essa chave: 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer sk-orca-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" },
    "request_id": "run-42-step-3"
  }'
O firewall resolve a política ativa do seu workspace e retorna o veredito — allow, audit, deny, sanitize, pending_approval, ou uma resolução cap_cost. Seu agente age sobre ele: despacha no allow, pula no deny, consulta o id de aprovação no pending_approval. A mesma chave de gateway autentica as rotas de consulta-de-aprovação e MCP.
Apontando um cliente MCP (Claude Desktop, Cursor, um framework de agente) para https://api.orcarouter.ai/api/v1/firewall/mcp? Use a chave de gateway como seu bearer token. Cada tools/call é então avaliado na superfície mcp antes de ser encaminhado upstream.

​
5. Onde isso se encaixa

Uma chave de gateway autentica as rotas de gateway. Ela não substitui a sessão de console que você usa para criar política: criar políticas, editar regras, registrar servidores MCP e resolver aprovações todos rodam sob sua própria sessão em /api/workspace/firewall/* (leituras de configurações, política e ferramentas descobertas abertas a cada membro; o sandbox de teste dry-run e todas as escritas exigem Developer+). A chave de gateway só carrega requisições de veredito e dispatch de MCP do seu runtime machine-to-machine.

Escopo: chaves, políticas, workspaces

Como o firewall_policy_id de uma chave e um escopo de gateway se relacionam com a fronteira do workspace.

Aprovações

O fluxo de chamada retida que sua chave de gateway consulta e reenvia.

Webhook de aprovação

O callback assinado por HMAC que resolve uma chamada retida fora de banda.

Servidores MCP

Registre e governe servidores MCP atrás do endpoint do gateway.

​
6. FAQ

Levantar is_firewall_gateway para true é Admin+. Uma escrita de papel Developer que define a flag é silenciosamente mantida em false (para que um rename ou edição de cota não relacionada na mesma requisição ainda tenha sucesso) — a chave apenas não carregará o escopo. Recrie-a ou edite-a como um Admin.
A chave apresentada não tem escopo de gateway. Confirme que ela foi cunhada com is_firewall_gateway = true por um Admin — uma chave de relay normal sempre recebe 403 nessas rotas. Veja §2.
Tecnicamente uma chave com escopo de gateway também pode servir tráfego de relay /v1/*, mas mantenha-as separadas: uma chave de relay (com firewall_policy_id vinculado) para modelos, uma chave de gateway para as rotas de evaluate/MCP/aprovação. Rotação independente, raio de explosão menor.
As chaves são mascaradas após a criação, e ler o texto plano de uma chave de gateway é Admin+. Se você não a copiou no momento de cunhar, crie uma nova chave de gateway e aposente a antiga.