Skip to main content
The Agent Firewall is configured two ways: through the console (your session, the same login you use for the dashboard) and through the gateway (a dedicated firewall-scoped API key your agent presents at runtime). The two families live at different path prefixes, take different auth, and answer different questions — “edit the policy” versus “evaluate this tool call.” This page is the route-by-route map of both. For what the policy means — verdicts, surfaces, rules, resolution — start at Firewall and Firewall rules. This page is the API surface only.

​
1. The two route families

Console — configure

/api/workspace/firewall/*. Authenticated by your session / access token (UserAuth), scoped to your active workspace. Author policies, read events, register MCP servers, resolve approvals. Every action is role-gated.

Gateway — enforce

/api/v1/firewall/*. Authenticated by a firewall-gateway-scoped key (a key with is_firewall_gateway set). The machine-to-machine surface your agent or MCP client calls at runtime. A regular relay key gets 403 here.
Console routes never take an sk-orca-… relay key, and gateway routes never take a session token. Mixing them up is the most common 401/403 when wiring the firewall up the first time. The only sk-orca-… key that belongs on a /v1/firewall/* call is one minted with is_firewall_gateway turned on — see Scope, keys & policies.

​
2. Roles at a glance

Console routes resolve your workspace role and gate accordingly. Reads that carry no tool-call provenance are open to any member; writes and anything exposing tool-call arguments require Developer+.
RoleCan do
Viewer / memberRead settings, policies, presets, discovered tools, simulate, anomalies.
Developer+All of the above, plus every write, the events/runs/trace surface, and the test dry-run.
Admin+Additionally, set the is_firewall_gateway flag on a key and read a gateway key’s plaintext.
The split is deliberate: a viewer can see that a policy exists and what it would block, but not the raw tool-call arguments behind an event. If you’re building dashboards for non-developers, the read-open routes are the safe set.

​
3. Configure a policy from the console

The console routes are how you author and inspect policy. You configure everything in the dashboard UI — these are the same endpoints it calls.

​
Policies & settings

Method & pathRolePurpose
GET /api/workspace/firewall/settingsMemberObserve-mode + counts.
PUT /api/workspace/firewall/settingsDeveloper+Update workspace firewall settings.
GET /api/workspace/firewall/policiesMemberList policies.
GET /api/workspace/firewall/policies/:idMemberSingle policy detail.
POST /api/workspace/firewall/policiesDeveloper+Create a policy.
PUT /api/workspace/firewall/policiesDeveloper+Update a policy.
DELETE /api/workspace/firewall/policies/:idDeveloper+Delete a policy.
POST /api/workspace/firewall/rulesDeveloper+Add a rule.
PUT /api/workspace/firewall/rulesDeveloper+Update a rule.
DELETE /api/workspace/firewall/rules/:idDeveloper+Delete a rule.

​
Posture, presets & sandboxes

Method & pathRolePurpose
GET /api/workspace/firewall/presetsMemberBuilt-in rule presets.
GET /api/workspace/firewall/templatesMemberUse-case template gallery.
POST /api/workspace/firewall/templates/applyDeveloper+Apply a template → one policy + its rules.
POST /api/workspace/firewall/autonomyDeveloper+Apply an autonomy level (tight / balanced / permissive).
POST /api/workspace/firewall/autonomy/undo/:audit_idDeveloper+One-click undo from the audit snapshot.
GET /api/workspace/firewall/simulateMemberWhat a level would block (?level=).
POST /api/workspace/firewall/testDeveloper+Dry-run a policy against a sample call.

​
Observability

Method & pathRolePurpose
GET /api/workspace/firewall/discovered-toolsMemberTools seen, flagged covered / gap.
GET /api/workspace/firewall/eventsDeveloper+List firewall events (filterable).
GET /api/workspace/firewall/events/by-request/:request_idDeveloper+Events for one request.
GET /api/workspace/firewall/events/aggregateDeveloper+Runs / sessions rollup.
GET /api/workspace/firewall/trace/by-runDeveloper+Trace nodes for a run (?run_id=).
GET /api/workspace/firewall/anomaliesMemberAnomaly feed.
POST /api/workspace/firewall/anomalies/snoozeDeveloper+Snooze the feed (≤ 7 days).

​
MCP servers

Register the Model Context Protocol servers your agents reach, behind one audited gateway. Credentials are stored encrypted and masked on read.
Method & pathRolePurpose
GET /api/workspace/firewall/mcp_serversMemberList registered servers.
GET /api/workspace/firewall/mcp_servers/:idMemberServer detail.
POST /api/workspace/firewall/mcp_serversDeveloper+Register a server (409 on a duplicate name).
PUT /api/workspace/firewall/mcp_serversDeveloper+Update a server.
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+Remove a server.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+Reachability + tools/list handshake.
A server carries a unique name, an endpoint, an auth_mode (none / bearer / oauth / basic), and a health status (ok / degraded / down). See Firewall MCP for the full lifecycle and skill quarantine.

​
4. Enforce at the gateway

These run on a firewall-gateway-scoped key, not your session. They’re what your agent loop or MCP client calls at runtime.
Method & pathPurpose
POST /api/v1/firewall/evaluatePre-dispatch verdict for one tool call.
POST /api/v1/firewall/evaluate_planPre-execution check for a multi-step plan.
ANY /api/v1/firewall/mcpThe unified MCP gateway endpoint.
GET /api/v1/firewall/mcp_serversEnumerate the workspace’s registered servers.
GET /api/v1/firewall/approvals/:idPoll a held call’s approval state.
POST /api/v1/firewall/approvals/:id/callbackHMAC-signed approval callback.

​
One concrete example: evaluate a tool call

Before your agent dispatches a tool, ask the gateway for a verdict. Pass the firewall-gateway-scoped key — not your relay sk-orca-… key: 
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 /" }
  }'
The response carries the verdict — allow, audit, deny, sanitize, or pending_approval. On deny you skip the call and surface the reason to the model; on sanitize you forward the cleaned arguments the gateway hands back (sanitize redacts tool-call arguments only — never the content a tool returns); on pending_approval you enter the approval loop below.
The gateway evaluates the calls that cross it — the evaluate hook, the MCP gateway, and the relay path. A tool your agent runs entirely in-process, never touching OrcaRouter, is outside its view. Route the calls that matter (model-mediated tools, MCP dispatch, network egress) through the gateway and they’re governed.

​
5. The approval handshake (HITL)

A pending_approval verdict holds the call for a human. The HTTP error while held is firewall_approval_pending. Clearing it is a three-step loop split across both route families:
1

A reviewer resolves the hold

From the console (PATCH /api/workspace/firewall/approvals/:id, Developer+), or your own system posts an HMAC-signed callback to POST /api/v1/firewall/approvals/:id/callback. The callback verifies the HMAC inline — no other auth is accepted.
2

Your agent polls the approval

GET /api/v1/firewall/approvals/:id with the gateway key, until the state flips to approved or rejected.
3

Re-submit with the single-use token

Once approved, re-issue the original call carrying the X-OrcaRouter-Firewall-Approval header with the approval id. The gateway recognizes it and lets that one call through. The header is single-use.
Decisions are first-writer-wins and idempotent — a second resolution of the same hold is a no-op. See Firewall — Human approval for the end-to-end flow and Why was this blocked? for reading a verdict.

​
6. What a block looks like

OutcomeHTTPCode
Denied tool call (inbound surface)400firewall_blocked
Denied via MCP gatewaytool errorfirewall deny: <reason>
Held for approval400firewall_approval_pending
firewall_blocked is marked skip-retry — re-running the identical call would just block again, so a retrying client backs off instead of hammering. The full code list lives in Error codes.

Guardrail API

The content-policy peer — /api/guardrail/* routes for the text plane.

Verdict glossary

Every verdict and what it does to a call.

Glob & JSONPath

The matching grammar behind tool_name_glob and args_match.

Compliance API

Packs, signed reports, residency, and erasure.

​
8. FAQ

The gateway routes require a firewall-gateway-scoped key — one minted with is_firewall_gateway set (an Admin+ action). A regular relay key, even a valid one, gets 403. Mint a dedicated gateway key for your agent runtime.
No. The events, events/aggregate, and trace routes are Developer+ because the records carry tool-call argument provenance. Viewers can read settings, policies, presets, discovered tools, simulate, and the anomaly feed.
Either. A human resolves it in the console via PATCH /api/workspace/firewall/approvals/:id (Developer+), or your own system posts an HMAC-signed decision to POST /api/v1/firewall/approvals/:id/callback. The agent polls GET /api/v1/firewall/approvals/:id regardless of which path resolved it.
No. A sanitize verdict redacts the tool-call arguments only — never the content a tool returns. On the inbound surface, where there are no call-time arguments yet, sanitize escalates to a block. See Firewall rules.
For how these controls compose with guardrails and the rest of the gateway, see Securing AI agents and Guardrails vs Firewall.