Skip to main content
To run tool calls through the agent firewall from outside the model relay — your own agent loop calling the evaluate hook, or an MCP client connecting to the MCP gateway — you authenticate with a dedicated firewall-gateway-scoped key, not an ordinary sk-orca-… relay key. A regular key gets 403 on the token-authenticated firewall gateway routes (the approval callback is the one exception — it’s HMAC-signed, not token-gated). This page covers what a firewall gateway api key is, how to mint one, and why the scope is gated to Admin+. For the engine itself, see the Firewall overview and the deep reference at Firewall.

​
1. What a firewall gateway api key is

Every token (API key) in your workspace carries an is_firewall_gateway flag. When it’s true, the key is allowed to reach the firewall gateway surface:
RouteWhat it does
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 MCP servers (returns decrypted upstream auth).
GET /api/v1/firewall/approvals/:idPoll a held call’s approval state.
A key with is_firewall_gateway = false (the default) is a normal relay key — it serves /v1/* model traffic and, if you’ve attached a policy via firewall_policy_id, its tool calls are governed inline. But it cannot call the gateway routes above.
Two different keys, two different jobs. Your relay key (firewall_policy_id attached) is what your agent uses to talk to models — the firewall governs its tool calls automatically. A firewall gateway key is what your agent runtime uses to ask the firewall for a verdict directly, or to proxy MCP tools/call through the gateway. Most workspaces only need a gateway key once they adopt the evaluate hook or the MCP gateway.

​
2. Why a regular key gets 403

The gateway scope unlocks two secret-sensitive capabilities, so it’s deliberately walled off from ordinary keys:
  • /evaluate accepts a caller-supplied request_id that flows into the firewall event and approval records. Any model key being able to forge audit events or silently probe policy outcomes would undermine the trail.
  • /mcp_servers returns decrypted upstream credentials so the SDK’s proxy can dispatch to your registered MCP servers. That’s a credential read, not a model call.
Because of this, the handler checks the presenting token’s is_firewall_gateway flag and returns HTTP 403 when it’s absent: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Don’t reuse a high-traffic relay key as a gateway key, and don’t reuse a gateway key for relay traffic. Keep the action-plane key separate so its blast radius and rotation are independent of your model keys.

​
3. Mint one — role-gated to Admin+

Setting is_firewall_gateway = true requires workspace Admin or above. A Developer can create and edit ordinary keys, but cannot mint a gateway-scoped one — the flag is a secret-management concern, so it sits above the normal token-write role. You configure keys in the console, under your workspace API keys. To mint a gateway key:
1

Open API keys as an Admin

Sign in as a workspace Admin (or higher) and open the API keys page in the console.
2

Create a key with the gateway scope

Create a new key and enable its firewall gateway scope (is_firewall_gateway). A Developer-role session won’t see the scope take effect — the server keeps the flag false for non-admins.
3

Copy the key once

Copy the full key value at creation. Afterwards the console masks it on display, and reading a gateway key’s plaintext back is itself Admin+ — non-admins get the gateway rows omitted from a “fetch my keys” response.
Lowering the flag is more permissive than raising it: clearing is_firewall_gateway (demoting a gateway key back to a normal key) is open to any role that can edit the key. Only raising it to true is Admin+.

​
Role gates at a glance

ActionRole
Create/edit an ordinary keyDeveloper+
Set is_firewall_gateway = trueAdmin+
Read a gateway key’s plaintext backAdmin+
Clear is_firewall_gateway (demote)any key-editor

​
4. One concrete example

You’re running an agent loop and want to check a tool call before dispatching it. As an Admin, mint a gateway key in the console, then call the evaluate hook from your runtime with that key: 
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"
  }'
The firewall resolves your workspace’s active policy and returns the verdict — allow, audit, deny, sanitize, pending_approval, or a cap_cost resolution. Your agent acts on it: dispatch on allow, skip on deny, poll the approval id on pending_approval. The same gateway key authenticates the approval-poll and MCP routes.
Pointing an MCP client (Claude Desktop, Cursor, an agent framework) at https://api.orcarouter.ai/api/v1/firewall/mcp? Use the gateway key as its bearer token. Every tools/call is then evaluated on the mcp surface before it’s forwarded upstream.

​
5. Where it fits

A gateway key authenticates the gateway routes. It does not replace the console session you use to author policy: creating policies, editing rules, registering MCP servers, and resolving approvals all run under your own session on /api/workspace/firewall/* (settings, policy, and discovered-tool reads open to every member; the dry-run test sandbox and all writes require Developer+). The gateway key only carries verdict requests and MCP dispatch from your machine-to-machine runtime.

Scope: keys, policies, workspaces

How a key’s firewall_policy_id and a gateway scope relate to the workspace boundary.

Approvals

The held-call flow your gateway key polls and re-submits.

Approval webhook

The HMAC-signed callback that resolves a held call out-of-band.

MCP servers

Register and govern MCP servers behind the gateway endpoint.

​
6. FAQ

Raising is_firewall_gateway to true is Admin+. A Developer-role write that sets the flag is silently kept at false (so an unrelated rename or quota edit on the same request still succeeds) — the key just won’t carry the scope. Re-create or edit it as an Admin.
The presenting key isn’t gateway-scoped. Confirm it was minted with is_firewall_gateway = true by an Admin — a normal relay key always gets 403 on these routes. See §2.
Technically a gateway-scoped key can also serve /v1/* relay traffic, but keep them separate: one relay key (with firewall_policy_id attached) for models, one gateway key for the evaluate/MCP/approval routes. Independent rotation, smaller blast radius.
Keys are masked after creation, and reading a gateway key’s plaintext is Admin+. If you didn’t copy it at mint time, create a new gateway key and retire the old one.