Zum Hauptinhalt springen
Um Tool-Calls von außerhalb des Modell-Relays durch die Agent-Firewall laufen zu lassen — Ihre eigene Agentenschleife, die den Evaluate-Hook aufruft, oder ein MCP-Client, der sich mit dem MCP-Gateway verbindet — authentifizieren Sie mit einem dedizierten firewall-gateway-scoped Key, nicht mit einem gewöhnlichen sk-orca-…-Relay-Key. Ein regulärer Key bekommt 403 auf den token-authentifizierten Firewall-Gateway-Routen (der Approval-Callback ist die eine Ausnahme — er ist HMAC-signiert, nicht token-gegated). Diese Seite behandelt, was ein Firewall-Gateway-API-Key ist, wie man einen prägt und warum der Scope auf Admin+ gegated ist. Für die Engine selbst siehe den Firewall-Überblick und die Tiefenreferenz unter Firewall.

​
1. Was ein Firewall-Gateway-API-Key ist

Jedes Token (API-Key) in Ihrem Workspace trägt ein is_firewall_gateway-Flag. Wenn es true ist, darf der Key die Firewall-Gateway-Surface erreichen:
RouteWas sie tut
POST /api/v1/firewall/evaluatePre-Dispatch-Verdikt für einen Tool-Call.
POST /api/v1/firewall/evaluate_planPre-Execution-Prüfung für einen mehrstufigen Plan.
ANY /api/v1/firewall/mcpDer vereinheitlichte MCP-Gateway-Endpunkt.
GET /api/v1/firewall/mcp_serversDie registrierten MCP-Server des Workspaces aufzählen (gibt entschlüsselte Upstream-Auth zurück).
GET /api/v1/firewall/approvals/:idDen Approval-Zustand eines zurückgehaltenen Aufrufs pollen.
Ein Key mit is_firewall_gateway = false (der Default) ist ein normaler Relay-Key — er bedient /v1/*-Modell-Traffic und, wenn Sie via firewall_policy_id eine Policy angehängt haben, werden seine Tool-Calls inline gesteuert. Aber er kann die obigen Gateway-Routen nicht aufrufen.
Zwei verschiedene Keys, zwei verschiedene Jobs. Ihr Relay-Key (mit angehängter firewall_policy_id) ist es, was Ihr Agent nutzt, um mit Modellen zu sprechen — die Firewall steuert seine Tool-Calls automatisch. Ein Firewall-Gateway-Key ist es, was Ihre Agent-Runtime nutzt, um die Firewall direkt um ein Verdikt zu bitten oder um MCP-tools/call durch das Gateway zu proxyen. Die meisten Workspaces brauchen einen Gateway-Key erst, wenn sie den Evaluate-Hook oder das MCP-Gateway adoptieren.

​
2. Warum ein regulärer Key 403 bekommt

Der Gateway-Scope schaltet zwei secret-sensible Fähigkeiten frei, daher ist er bewusst von gewöhnlichen Keys abgeschottet:
  • /evaluate akzeptiert eine aufrufer-gelieferte request_id, die in die Firewall-Event- und Approval-Datensätze fließt. Wenn irgendein Modell-Key Audit-Events fälschen oder still Policy-Ergebnisse abtasten könnte, würde das die Spur untergraben.
  • /mcp_servers gibt entschlüsselte Upstream-Credentials zurück, sodass der Proxy des SDK an Ihre registrierten MCP-Server dispatchen kann. Das ist ein Credential-Read, kein Modellaufruf.
Deshalb prüft der Handler das is_firewall_gateway-Flag des präsentierten Tokens und gibt HTTP 403 zurück, wenn es fehlt: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Verwenden Sie keinen hochfrequentierten Relay-Key als Gateway-Key wieder, und verwenden Sie keinen Gateway-Key für Relay-Traffic wieder. Halten Sie den Aktionsebenen-Key separat, sodass sein Wirkungsradius und seine Rotation unabhängig von Ihren Modell-Keys sind.

​
3. Einen prägen — rollengesteuert auf Admin+

is_firewall_gateway = true zu setzen erfordert Workspace-Admin oder höher. Ein Developer kann gewöhnliche Keys erstellen und bearbeiten, aber keinen gateway-gescopten prägen — das Flag ist ein Secret-Management-Anliegen, sodass es über der normalen Token-Write-Rolle sitzt. Sie konfigurieren Keys in der Konsole, unter Ihren Workspace-API-Keys. Um einen Gateway-Key zu prägen:
1

API-Keys als Admin öffnen

Melden Sie sich als Workspace-Admin (oder höher) an und öffnen Sie die API-Keys-Seite in der Konsole.
2

Einen Key mit dem Gateway-Scope erstellen

Erstellen Sie einen neuen Key und aktivieren Sie seinen Firewall-Gateway-Scope (is_firewall_gateway). Eine Developer-Rollen-Session wird den Scope nicht wirksam werden sehen — der Server hält das Flag für Nicht-Admins auf false.
3

Den Key einmal kopieren

Kopieren Sie den vollständigen Key-Wert bei der Erstellung. Danach maskiert die Konsole ihn bei der Anzeige, und das Zurücklesen des Klartexts eines Gateway-Keys ist selbst Admin+ — Nicht-Admins bekommen die Gateway-Zeilen aus einer „fetch my keys”-Antwort weggelassen.
Das Senken des Flags ist permissiver als das Anheben: das Löschen von is_firewall_gateway (einen Gateway-Key zurück zu einem normalen Key degradieren) ist für jede Rolle offen, die den Key bearbeiten kann. Nur das Anheben auf true ist Admin+.

​
Rollen-Gates auf einen Blick

AktionRolle
Einen gewöhnlichen Key erstellen/bearbeitenDeveloper+
is_firewall_gateway = true setzenAdmin+
Den Klartext eines Gateway-Keys zurücklesenAdmin+
is_firewall_gateway löschen (degradieren)jeder Key-Editor

​
4. Ein konkretes Beispiel

Sie führen eine Agentenschleife aus und wollen einen Tool-Call prüfen, bevor Sie ihn dispatchen. Prägen Sie als Admin einen Gateway-Key in der Konsole und rufen Sie dann den Evaluate-Hook aus Ihrer Runtime mit diesem Key auf: 
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"
  }'
Die Firewall löst die aktive Policy Ihres Workspaces auf und gibt das Verdikt zurück — allow, audit, deny, sanitize, pending_approval oder eine cap_cost-Auflösung. Ihr Agent handelt danach: dispatchen bei allow, überspringen bei deny, die Approval-ID pollen bei pending_approval. Derselbe Gateway-Key authentifiziert die Approval-Poll- und MCP-Routen.
Sie richten einen MCP-Client (Claude Desktop, Cursor, ein Agenten-Framework) auf https://api.orcarouter.ai/api/v1/firewall/mcp? Verwenden Sie den Gateway-Key als sein Bearer-Token. Jeder tools/call wird dann auf der mcp-Surface ausgewertet, bevor er upstream weitergeleitet wird.

​
5. Wo es hineinpasst

Ein Gateway-Key authentifiziert die Gateway-Routen. Er ersetzt nicht die Konsolen-Session, die Sie zum Verfassen von Policy nutzen: Policies erstellen, Regeln bearbeiten, MCP-Server registrieren und Approvals auflösen laufen alle unter Ihrer eigenen Session auf /api/workspace/firewall/* (Einstellungs-, Policy- und Discovered-Tool-Reads für jedes Member offen; die Dry-run-Test-Sandbox und alle Writes erfordern Developer+). Der Gateway-Key trägt nur Verdikt-Requests und MCP-Dispatch von Ihrer Maschine-zu-Maschine-Runtime.

Scope: Keys, Policies, Workspaces

Wie sich die firewall_policy_id eines Keys und ein Gateway-Scope zur Workspace-Grenze verhalten.

Approvals

Der Held-Call-Flow, den Ihr Gateway-Key pollt und erneut einreicht.

Approval-Webhook

Der HMAC-signierte Callback, der einen zurückgehaltenen Aufruf out-of-band auflöst.

MCP-Server

MCP-Server hinter dem Gateway-Endpunkt registrieren und steuern.

​
6. FAQ

Das Anheben von is_firewall_gateway auf true ist Admin+. Ein Developer-Rollen-Write, der das Flag setzt, wird still auf false gehalten (sodass ein unzusammenhängendes Rename oder eine Quota-Bearbeitung auf demselben Request trotzdem gelingt) — der Key trägt den Scope einfach nicht. Erstellen oder bearbeiten Sie ihn als Admin neu.
Der präsentierte Key ist nicht gateway-gescopt. Bestätigen Sie, dass er von einem Admin mit is_firewall_gateway = true geprägt wurde — ein normaler Relay-Key bekommt auf diesen Routen immer 403. Siehe §2.
Technisch kann ein gateway-gescopter Key auch /v1/*-Relay-Traffic bedienen, aber halten Sie sie separat: ein Relay-Key (mit angehängter firewall_policy_id) für Modelle, ein Gateway-Key für die Evaluate-/MCP-/Approval-Routen. Unabhängige Rotation, kleinerer Wirkungsradius.
Keys werden nach der Erstellung maskiert, und das Lesen des Klartexts eines Gateway-Keys ist Admin+. Wenn Sie ihn nicht zur Prägezeit kopiert haben, erstellen Sie einen neuen Gateway-Key und mustern den alten aus.