Vai al contenuto principale
Per far girare le chiamate a tool attraverso l’agent firewall dall’esterno del relay del modello — il tuo loop di agent che chiama l’hook di evaluate, o un client MCP che si connette al gateway MCP — ti autentichi con una chiave dedicata con scope firewall-gateway, non con una normale chiave di relay sk-orca-…. Una chiave normale riceve 403 sulle rotte del gateway del firewall autenticate con token (il callback di approvazione è l’unica eccezione — è firmato con HMAC, non gated da token). Questa pagina copre cos’è una chiave API firewall-gateway, come coniarne una, e perché lo scope è gated ad Admin+. Per il motore stesso, vedi la Panoramica del Firewall e il riferimento approfondito in Firewall.

​
1. Cos’è una chiave API firewall-gateway

Ogni token (chiave API) nel tuo workspace porta un flag is_firewall_gateway. Quando è true, la chiave è autorizzata a raggiungere la superficie del gateway del firewall:
RottaCosa fa
POST /api/v1/firewall/evaluateVerdetto pre-dispatch per una chiamata a tool.
POST /api/v1/firewall/evaluate_planControllo pre-esecuzione per un piano multi-step.
ANY /api/v1/firewall/mcpL’endpoint unificato del gateway MCP.
GET /api/v1/firewall/mcp_serversEnumera gli MCP server registrati del workspace (restituisce l’auth upstream decifrata).
GET /api/v1/firewall/approvals/:idFa polling sullo stato di approvazione di una chiamata in attesa.
Una chiave con is_firewall_gateway = false (il default) è una normale chiave di relay — serve il traffico al modello /v1/* e, se hai collegato una policy tramite firewall_policy_id, le sue chiamate a tool sono governate inline. Ma non può chiamare le rotte del gateway sopra.
Due chiavi diverse, due compiti diversi. La tua chiave di relay (firewall_policy_id collegato) è ciò che il tuo agent usa per parlare con i modelli — il firewall governa automaticamente le sue chiamate a tool. Una chiave del gateway del firewall è ciò che il runtime del tuo agent usa per chiedere al firewall un verdetto direttamente, o per fare da proxy del tools/call MCP attraverso il gateway. La maggior parte dei workspace ha bisogno di una chiave del gateway solo una volta che adotta l’hook di evaluate o il gateway MCP.

​
2. Perché una chiave normale riceve 403

Lo scope del gateway sblocca due capability sensibili ai segreti, quindi è deliberatamente isolato dalle chiavi normali:
  • /evaluate accetta un request_id fornito dal chiamante che scorre nell’evento del firewall e nei record di approvazione. Se qualsiasi chiave del modello potesse falsificare eventi di audit o sondare silenziosamente gli esiti della policy, ciò minerebbe la traccia.
  • /mcp_servers restituisce credenziali upstream decifrate così il proxy dell’SDK può dispatchare verso i tuoi MCP server registrati. Quella è una lettura di credenziali, non una chiamata al modello.
Per questo, l’handler controlla il flag is_firewall_gateway del token presentato e restituisce HTTP 403 quando è assente: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Non riutilizzare una chiave di relay ad alto traffico come chiave del gateway, e non riutilizzare una chiave del gateway per il traffico di relay. Mantieni separata la chiave del piano-azione così il suo raggio d’impatto e la sua rotazione sono indipendenti dalle tue chiavi del modello.

​
3. Coniane una — role-gated ad Admin+

Impostare is_firewall_gateway = true richiede Admin del workspace o superiore. Un Developer può creare e modificare chiavi normali, ma non può coniarne una con scope sul gateway — il flag è una questione di gestione dei segreti, quindi sta sopra il normale ruolo di scrittura dei token. Configuri le chiavi nella console, sotto le chiavi API del tuo workspace. Per coniare una chiave del gateway:
1

Apri le chiavi API come Admin

Accedi come Admin del workspace (o superiore) e apri la pagina delle chiavi API nella console.
2

Crea una chiave con lo scope del gateway

Crea una nuova chiave e abilita il suo scope firewall gateway (is_firewall_gateway). Una sessione di ruolo Developer non vedrà lo scope avere effetto — il server mantiene il flag false per i non-admin.
3

Copia la chiave una volta

Copia il valore completo della chiave alla creazione. In seguito la console la maschera alla visualizzazione, e rileggere il plaintext di una chiave del gateway è esso stesso Admin+ — i non-admin ottengono le righe del gateway omesse da una risposta “fetch my keys”.
Abbassare il flag è più permissivo che alzarlo: azzerare is_firewall_gateway (declassare una chiave del gateway di nuovo a chiave normale) è aperto a qualsiasi ruolo che può modificare la chiave. Solo alzarlo a true è Admin+.

​
Gate dei ruoli in breve

AzioneRuolo
Creare/modificare una chiave normaleDeveloper+
Impostare is_firewall_gateway = trueAdmin+
Rileggere il plaintext di una chiave del gatewayAdmin+
Azzerare is_firewall_gateway (declassare)qualsiasi editor di chiavi

​
4. Un esempio concreto

Stai facendo girare un loop di agent e vuoi controllare una chiamata a tool prima di dispatcharla. Come Admin, conia una chiave del gateway nella console, poi chiama l’hook di evaluate dal tuo runtime con quella chiave: 
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"
  }'
Il firewall risolve la policy attiva del tuo workspace e restituisce il verdetto — allow, audit, deny, sanitize, pending_approval, o una risoluzione di cap_cost. Il tuo agent agisce su di esso: dispatcha su allow, salta su deny, fa polling sull’id di approvazione su pending_approval. La stessa chiave del gateway autentica le rotte di polling dell’approvazione e MCP.
Stai puntando un client MCP (Claude Desktop, Cursor, un framework per agent) su https://api.orcarouter.ai/api/v1/firewall/mcp? Usa la chiave del gateway come suo bearer token. Ogni tools/call viene allora valutato sulla superficie mcp prima di essere inoltrato upstream.

​
5. Dove si inserisce

Una chiave del gateway autentica le rotte del gateway. Non sostituisce la sessione di console che usi per scrivere la policy: creare policy, modificare regole, registrare MCP server e risolvere approvazioni girano tutti sotto la tua sessione su /api/workspace/firewall/* (le letture di impostazioni, policy e discovered tools aperte a ogni membro; la sandbox di test di dry-run e tutte le scritture richiedono Developer+). La chiave del gateway porta solo le richieste di verdetto e il dispatch MCP dal tuo runtime machine-to-machine.

Scope: chiavi, policy, workspace

Come il firewall_policy_id di una chiave e uno scope del gateway si relazionano al confine del workspace.

Approvazioni

Il flusso della chiamata in attesa su cui la tua chiave del gateway fa polling e ri-invia.

Webhook di approvazione

Il callback firmato con HMAC che risolve una chiamata in attesa fuori banda.

MCP server

Registra e governa gli MCP server dietro l’endpoint del gateway.

​
6. FAQ

Alzare is_firewall_gateway a true è Admin+. Una scrittura di ruolo Developer che imposta il flag viene silenziosamente mantenuta a false (così un rename o una modifica di quota non correlati sulla stessa richiesta hanno comunque successo) — la chiave semplicemente non porterà lo scope. Ricreala o modificala come Admin.
La chiave presentata non ha scope sul gateway. Conferma che sia stata coniata con is_firewall_gateway = true da un Admin — una normale chiave di relay riceve sempre 403 su queste rotte. Vedi §2.
Tecnicamente una chiave con scope sul gateway può anche servire il traffico di relay /v1/*, ma tienile separate: una chiave di relay (con firewall_policy_id collegato) per i modelli, una chiave del gateway per le rotte di evaluate/MCP/approvazione. Rotazione indipendente, raggio d’impatto più piccolo.
Le chiavi sono mascherate dopo la creazione, e leggere il plaintext di una chiave del gateway è Admin+. Se non l’hai copiata al momento della coniatura, crea una nuova chiave del gateway e ritira la vecchia.