Passer au contenu principal
L’Agent Firewall se configure de deux façons : via la console (votre session, le même login que vous utilisez pour le dashboard) et via la passerelle (une clé API dédiée scopée au firewall que votre agent présente à l’exécution). Les deux familles vivent à des préfixes de chemin différents, prennent une auth différente, et répondent à des questions différentes — « éditer la politique » versus « évaluer cet appel d’outil ». Cette page est la carte route par route des deux. Pour savoir ce que la politique signifie — verdicts, surfaces, règles, résolution — commencez à Firewall et Règles du Firewall. Cette page est uniquement la surface d’API.

​
1. Les deux familles de routes

Console — configurer

/api/workspace/firewall/*. Authentifiée par votre token de session / accès (UserAuth), scopée à votre espace de travail actif. Rédigez des politiques, lisez des événements, enregistrez des serveurs MCP, résolvez des approbations. Chaque action est gardée par rôle.

Passerelle — appliquer

/api/v1/firewall/*. Authentifiée par une clé scopée à la passerelle firewall (une clé avec is_firewall_gateway activé). La surface machine-à-machine que votre agent ou client MCP appelle à l’exécution. Une clé de relais ordinaire reçoit un 403 ici.
Les routes de console ne prennent jamais une clé de relais sk-orca-…, et les routes de passerelle ne prennent jamais un token de session. Les confondre est le 401/403 le plus fréquent lors du premier câblage du firewall. La seule clé sk-orca-… qui a sa place sur un appel /v1/firewall/* est une clé frappée avec is_firewall_gateway activé — voir Portée, clés et politiques.

​
2. Les rôles en un coup d’œil

Les routes de console résolvent votre rôle d’espace de travail et gardent en conséquence. Les lectures qui ne portent aucune provenance d’appel d’outil sont ouvertes à tout membre ; les écritures et tout ce qui expose des arguments d’appel d’outil requièrent Developer+.
RôlePeut faire
Viewer / membreLire les réglages, politiques, presets, outils découverts, simuler, anomalies.
Developer+Tout ce qui précède, plus chaque écriture, la surface events/runs/trace, et le dry-run test.
Admin+En plus, activer le flag is_firewall_gateway sur une clé et lire le texte en clair d’une clé de passerelle.
Le partage est délibéré : un viewer peut voir *qu’*une politique existe et ce qu’elle bloquerait, mais pas les arguments bruts de l’appel d’outil derrière un événement. Si vous construisez des dashboards pour des non-développeurs, les routes ouvertes en lecture sont l’ensemble sûr.

​
3. Configurer une politique depuis la console

Les routes de console sont la manière dont vous rédigez et inspectez une politique. Vous configurez tout dans l’UI du dashboard — ce sont les mêmes endpoints qu’elle appelle.

​
Politiques & réglages

Méthode & cheminRôleObjectif
GET /api/workspace/firewall/settingsMemberMode observe + comptes.
PUT /api/workspace/firewall/settingsDeveloper+Mettre à jour les réglages firewall de l’espace de travail.
GET /api/workspace/firewall/policiesMemberLister les politiques.
GET /api/workspace/firewall/policies/:idMemberDétail d’une seule politique.
POST /api/workspace/firewall/policiesDeveloper+Créer une politique.
PUT /api/workspace/firewall/policiesDeveloper+Mettre à jour une politique.
DELETE /api/workspace/firewall/policies/:idDeveloper+Supprimer une politique.
POST /api/workspace/firewall/rulesDeveloper+Ajouter une règle.
PUT /api/workspace/firewall/rulesDeveloper+Mettre à jour une règle.
DELETE /api/workspace/firewall/rules/:idDeveloper+Supprimer une règle.

​
Posture, presets & sandboxes

Méthode & cheminRôleObjectif
GET /api/workspace/firewall/presetsMemberPresets de règles intégrés.
GET /api/workspace/firewall/templatesMemberGalerie de templates par cas d’usage.
POST /api/workspace/firewall/templates/applyDeveloper+Appliquer un template → une politique + ses règles.
POST /api/workspace/firewall/autonomyDeveloper+Appliquer un niveau d’autonomie (tight / balanced / permissive).
POST /api/workspace/firewall/autonomy/undo/:audit_idDeveloper+Annulation en un clic depuis le snapshot d’audit.
GET /api/workspace/firewall/simulateMemberCe qu’un niveau bloquerait (?level=).
POST /api/workspace/firewall/testDeveloper+Exécuter en dry-run une politique contre un appel d’échantillon.

​
Observabilité

Méthode & cheminRôleObjectif
GET /api/workspace/firewall/discovered-toolsMemberOutils vus, marqués covered / gap.
GET /api/workspace/firewall/eventsDeveloper+Lister les événements firewall (filtrables).
GET /api/workspace/firewall/events/by-request/:request_idDeveloper+Événements pour une requête.
GET /api/workspace/firewall/events/aggregateDeveloper+Récapitulatif par exécutions / sessions.
GET /api/workspace/firewall/trace/by-runDeveloper+Nœuds de trace pour une exécution (?run_id=).
GET /api/workspace/firewall/anomaliesMemberFlux d’anomalies.
POST /api/workspace/firewall/anomalies/snoozeDeveloper+Mettre en sourdine le flux (≤ 7 jours).

​
Serveurs MCP

Enregistrez les serveurs Model Context Protocol que vos agents atteignent, derrière une seule passerelle auditée. Les identifiants sont stockés chiffrés et masqués à la lecture.
Méthode & cheminRôleObjectif
GET /api/workspace/firewall/mcp_serversMemberLister les serveurs enregistrés.
GET /api/workspace/firewall/mcp_servers/:idMemberDétail d’un serveur.
POST /api/workspace/firewall/mcp_serversDeveloper+Enregistrer un serveur (409 sur un name en double).
PUT /api/workspace/firewall/mcp_serversDeveloper+Mettre à jour un serveur.
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+Retirer un serveur.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+Handshake de joignabilité + tools/list.
Un serveur porte un name unique, un endpoint, un auth_mode (none / bearer / oauth / basic), et un status de santé (ok / degraded / down). Voir Firewall MCP pour le cycle de vie complet et la mise en quarantaine des skills.

​
4. Appliquer à la passerelle

Celles-ci s’exécutent sur une clé scopée à la passerelle firewall, pas sur votre session. Ce sont celles que votre boucle d’agent ou client MCP appelle à l’exécution.
Méthode & cheminObjectif
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 enregistrés de l’espace de travail.
GET /api/v1/firewall/approvals/:idInterroger l’état d’approbation d’un appel en attente.
POST /api/v1/firewall/approvals/:id/callbackCallback d’approbation signé HMAC.

​
Un exemple concret : évaluer un appel d’outil

Avant que votre agent ne dispatche un outil, demandez un verdict à la passerelle. Passez la clé scopée à la passerelle firewall — pas votre clé de relais sk-orca-… : 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'
La réponse porte le verdict — allow, audit, deny, sanitize, ou pending_approval. Sur deny vous sautez l’appel et faites remonter la raison au modèle ; sur sanitize vous transmettez les arguments nettoyés que la passerelle vous rend (sanitize redacte uniquement les arguments de l’appel d’outil — jamais le contenu qu’un outil renvoie) ; sur pending_approval vous entrez dans la boucle d’approbation ci-dessous.
La passerelle évalue les appels qui la traversent — le hook evaluate, la passerelle MCP, et le chemin de relais. Un outil que votre agent exécute entièrement en interne, sans jamais toucher OrcaRouter, est hors de sa vue. Routez les appels qui comptent (outils médiés par le modèle, dispatch MCP, egress réseau) à travers la passerelle et ils sont gouvernés.

​
5. Le handshake d’approbation (HITL)

Un verdict pending_approval met l’appel en attente d’un humain. L’erreur HTTP pendant l’attente est firewall_approval_pending. Le débloquer est une boucle en trois étapes répartie sur les deux familles de routes :
1

Un relecteur résout la mise en attente

Depuis la console (PATCH /api/workspace/firewall/approvals/:id, Developer+), ou votre propre système poste un callback signé HMAC vers POST /api/v1/firewall/approvals/:id/callback. Le callback vérifie le HMAC en ligne — aucune autre auth n’est acceptée.
2

Votre agent interroge l'approbation

GET /api/v1/firewall/approvals/:id avec la clé de passerelle, jusqu’à ce que l’état bascule en approuvé ou rejeté.
3

Re-soumettre avec le token à usage unique

Une fois approuvé, ré-émettez l’appel d’origine en portant l’en-tête X-OrcaRouter-Firewall-Approval avec l’id d’approbation. La passerelle le reconnaît et laisse passer cet appel-là. L’en-tête est à usage unique.
Les décisions sont first-writer-wins et idempotentes — une seconde résolution de la même mise en attente est un no-op. Voir Firewall — Approbation humaine pour le flux de bout en bout et Pourquoi a-ce été bloqué ? pour lire un verdict.

​
6. À quoi ressemble un block

IssueHTTPCode
Appel d’outil refusé (surface inbound)400firewall_blocked
Refusé via la passerelle MCPerreur d’outilfirewall deny: <reason>
Mis en attente d’approbation400firewall_approval_pending
firewall_blocked est marqué skip-retry — ré-exécuter l’appel identique ne ferait que bloquer à nouveau, donc un client qui réessaie temporise plutôt que de marteler. La liste complète des codes vit dans Codes d’erreur.

​
7. Références associées

API Guardrail

Le pair de la politique de contenu — les routes /api/guardrail/* pour le plan de texte.

Glossaire des verdicts

Chaque verdict et ce qu’il fait à un appel.

Glob et JSONPath

La grammaire de correspondance derrière tool_name_glob et args_match.

API Compliance

Packs, rapports signés, résidence, et effacement.

​
8. FAQ

Les routes de passerelle requièrent une clé scopée à la passerelle firewall — une clé frappée avec is_firewall_gateway activé (une action Admin+). Une clé de relais ordinaire, même valide, reçoit un 403. Frappez une clé de passerelle dédiée pour votre runtime d’agent.
Non. Les routes events, events/aggregate, et trace sont Developer+ parce que les enregistrements portent la provenance des arguments d’appel d’outil. Les viewers peuvent lire les réglages, politiques, presets, outils découverts, simuler, et le flux d’anomalies.
L’un ou l’autre. Un humain la résout dans la console via PATCH /api/workspace/firewall/approvals/:id (Developer+), ou votre propre système poste une décision signée HMAC vers POST /api/v1/firewall/approvals/:id/callback. L’agent interroge GET /api/v1/firewall/approvals/:id peu importe quel chemin l’a résolue.
Non. Un verdict sanitize redacte uniquement les arguments de l’appel d’outil — jamais le contenu qu’un outil renvoie. Sur la surface inbound, où il n’y a pas encore d’arguments au moment de l’appel, sanitize escalade en un block. Voir Règles du Firewall.
Pour savoir comment ces contrôles se composent avec les guardrails et le reste de la passerelle, voir Sécuriser les agents IA et Guardrails vs Firewall.