Passer au contenu principal
Pour faire passer des appels d’outils à travers le firewall agent depuis l’extérieur du relais de modèle — votre propre boucle d’agent appelant le hook evaluate, ou un client MCP se connectant à la passerelle MCP — vous vous authentifiez avec une clé dédiée scopée à la passerelle firewall, pas une clé de relais sk-orca-… ordinaire. Une clé ordinaire reçoit un 403 sur les routes de passerelle firewall authentifiées par token (le callback d’approbation est l’unique exception — il est signé HMAC, pas filtré par token). Cette page couvre ce qu’est une clé api de passerelle firewall, comment en frapper une, et pourquoi la portée est filtrée à Admin+. Pour le moteur lui-même, voir la Vue d’ensemble du Firewall et la référence approfondie dans Firewall.

​
1. Ce qu’est une clé api de passerelle firewall

Chaque token (clé API) de votre espace de travail porte un flag is_firewall_gateway. Quand il est true, la clé est autorisée à atteindre la surface de passerelle firewall :
RouteCe qu’elle fait
POST /api/v1/firewall/evaluateVerdict pré-dispatch pour un appel d’outil.
POST /api/v1/firewall/evaluate_planVérification pré-exécution pour un plan multi-étapes.
ANY /api/v1/firewall/mcpL’endpoint unifié de la passerelle MCP.
GET /api/v1/firewall/mcp_serversÉnumérer les serveurs MCP enregistrés de l’espace de travail (renvoie l’auth amont déchiffrée).
GET /api/v1/firewall/approvals/:idInterroger l’état d’approbation d’un appel mis en attente.
Une clé avec is_firewall_gateway = false (le défaut) est une clé de relais normale — elle sert le trafic de modèle /v1/* et, si vous avez attaché une politique via firewall_policy_id, ses appels d’outils sont gouvernés en ligne. Mais elle ne peut pas appeler les routes de passerelle ci-dessus.
Deux clés différentes, deux jobs différents. Votre clé de relais (firewall_policy_id attaché) est ce que votre agent utilise pour parler aux modèles — le firewall gouverne ses appels d’outils automatiquement. Une clé de passerelle firewall est ce que le runtime de votre agent utilise pour demander un verdict au firewall directement, ou pour proxyfier les tools/call MCP à travers la passerelle. La plupart des espaces de travail n’ont besoin d’une clé de passerelle qu’une fois qu’ils adoptent le hook evaluate ou la passerelle MCP.

​
2. Pourquoi une clé ordinaire reçoit un 403

La portée de passerelle débloque deux capacités sensibles aux secrets, donc elle est délibérément cloisonnée des clés ordinaires :
  • /evaluate accepte un request_id fourni par l’appelant qui circule dans l’événement firewall et les enregistrements d’approbation. Qu’une clé de modèle quelconque puisse forger des événements d’audit ou sonder silencieusement les résultats de politique saperait la trace.
  • /mcp_servers renvoie des identifiants amont déchiffrés pour que le proxy du SDK puisse dispatcher vers vos serveurs MCP enregistrés. C’est une lecture d’identifiant, pas un appel de modèle.
À cause de cela, le handler vérifie le flag is_firewall_gateway du token présenté et renvoie HTTP 403 quand il est absent : 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Ne réutilisez pas une clé de relais à fort trafic comme clé de passerelle, et ne réutilisez pas une clé de passerelle pour le trafic de relais. Gardez la clé du plan action séparée pour que son rayon d’impact et sa rotation soient indépendants de vos clés de modèle.

​
3. En frapper une — filtré par rôle à Admin+

Définir is_firewall_gateway = true requiert Admin d’espace de travail ou au-dessus. Un Developer peut créer et éditer des clés ordinaires, mais ne peut pas frapper une clé scopée à la passerelle — le flag est une affaire de gestion de secrets, donc il se situe au-dessus du rôle normal d’écriture de token. Vous configurez les clés dans la console, sous les clés API de votre espace de travail. Pour frapper une clé de passerelle :
1

Ouvrir les clés API en tant qu'Admin

Connectez-vous en tant qu’Admin d’espace de travail (ou supérieur) et ouvrez la page des clés API dans la console.
2

Créer une clé avec la portée passerelle

Créez une nouvelle clé et activez sa portée firewall gateway (is_firewall_gateway). Une session de rôle Developer ne verra pas la portée prendre effet — le serveur garde le flag false pour les non-admins.
3

Copier la clé une fois

Copiez la valeur complète de la clé à la création. Ensuite, la console la masque à l’affichage, et relire le plaintext d’une clé de passerelle est elle-même Admin+ — les non-admins voient les lignes de passerelle omises d’une réponse « récupérer mes clés ».
Abaisser le flag est plus permissif que le lever : effacer is_firewall_gateway (rétrograder une clé de passerelle en clé normale) est ouvert à tout rôle qui peut éditer la clé. Seul le lever à true est Admin+.

​
Portes de rôle en un coup d’œil

ActionRôle
Créer/éditer une clé ordinaireDeveloper+
Définir is_firewall_gateway = trueAdmin+
Relire le plaintext d’une clé de passerelleAdmin+
Effacer is_firewall_gateway (rétrograder)tout éditeur de clé

​
4. Un exemple concret

Vous exécutez une boucle d’agent et voulez vérifier un appel d’outil avant de le dispatcher. En tant qu’Admin, frappez une clé de passerelle dans la console, puis appelez le hook evaluate depuis votre runtime avec cette clé : 
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"
  }'
Le firewall résout la politique active de votre espace de travail et renvoie le verdict — allow, audit, deny, sanitize, pending_approval, ou une résolution cap_cost. Votre agent agit dessus : dispatch sur allow, saut sur deny, interrogation de l’id d’approbation sur pending_approval. La même clé de passerelle authentifie les routes d’interrogation d’approbation et MCP.
Vous pointez un client MCP (Claude Desktop, Cursor, un framework d’agent) vers https://api.orcarouter.ai/api/v1/firewall/mcp ? Utilisez la clé de passerelle comme son bearer token. Chaque tools/call est alors évalué sur la surface mcp avant d’être transmis en amont.

​
5. Où cela s’insère

Une clé de passerelle authentifie les routes de passerelle. Elle ne remplace pas la session console que vous utilisez pour rédiger la politique : créer des politiques, éditer des règles, enregistrer des serveurs MCP et résoudre des approbations s’exécutent tous sous votre propre session sur /api/workspace/firewall/* (les lectures de réglages, de politique et d’outils découverts ouvertes à chaque membre ; le sandbox de test en dry-run et toutes les écritures requièrent Developer+). La clé de passerelle ne porte que les requêtes de verdict et le dispatch MCP depuis votre runtime machine-à-machine.

Portée : clés, politiques, espaces de travail

Comment le firewall_policy_id d’une clé et une portée de passerelle se rapportent à la frontière de l’espace de travail.

Approbations

Le flux d’appel mis en attente que votre clé de passerelle interroge et re-soumet.

Webhook d'approbation

Le callback signé HMAC qui résout un appel mis en attente hors-bande.

Serveurs MCP

Enregistrer et gouverner les serveurs MCP derrière l’endpoint de passerelle.

​
6. FAQ

Lever is_firewall_gateway à true est Admin+. Une écriture de rôle Developer qui définit le flag est silencieusement gardée à false (de sorte qu’un renommage ou une édition de quota non lié sur la même requête réussit quand même) — la clé ne portera simplement pas la portée. Re-créez-la ou éditez-la en tant qu’Admin.
La clé présentée n’est pas scopée à la passerelle. Confirmez qu’elle a été frappée avec is_firewall_gateway = true par un Admin — une clé de relais normale reçoit toujours un 403 sur ces routes. Voir §2.
Techniquement, une clé scopée à la passerelle peut aussi servir le trafic de relais /v1/*, mais gardez-les séparées : une clé de relais (avec firewall_policy_id attaché) pour les modèles, une clé de passerelle pour les routes evaluate/MCP/approbation. Rotation indépendante, rayon d’impact plus petit.
Les clés sont masquées après la création, et relire le plaintext d’une clé de passerelle est Admin+. Si vous ne l’avez pas copiée au moment de la frappe, créez une nouvelle clé de passerelle et retirez l’ancienne.