Skip to main content
Every request that reaches OrcaRouter carries an API key. That key is not just a credential — it is a scope declaration: which models the caller may use, which IPs may present it, how much it may spend, and exactly which guardrail and firewall policy govern its traffic. This page explains the three-level hierarchy and how policies resolve at request time.

​
1. The three scopes

Three concepts nest inside each other:
  • Workspace — the tenant boundary. Every member of a workspace shares the same guardrail and firewall policy catalog. Nothing crosses workspace boundaries — a policy authored in workspace A is invisible to workspace B.
  • Policy — a named, workspace-scoped rule set (guardrail or firewall policy). Editing a policy takes effect on every key attached to it on the next request, with no redeploy.
  • Key — identity plus attachments. A key carries its own constraints and points to the policies that govern it.
The workspace is the outer boundary; policies are shared resources inside it; keys are the per-agent identities that tie constraints and policies together.

​
2. What a key carries

Each API key is a bundle of limits and attachments. Set these in the key editor (/console/token) — creating or editing keys requires the Developer role or above.
FieldWhat it limitsMinimum role to set
model_limitsRestricts the key to a specific list of models — any call outside that list is rejected before it leaves the gateway.Developer
allow_ipsIP allow-list. Requests from any unlisted address are rejected at the auth layer. Empty means all IPs are allowed.Developer
credit_limit_usdSpend cap in USD. 0 means unlimited. The gateway enforces this against the key’s lifetime spend.Developer
expired_timeAbsolute expiry timestamp. -1 means the key never expires.Developer
environmentA freeform label (e.g. prod, staging, dev) for organizing keys and filtering logs.Developer
guardrail_idAttaches a specific guardrail to this key. Every call this key makes is screened by that guardrail.Developer
firewall_policy_idAttaches a specific firewall policy to this key. Every tool call this key issues is evaluated by that policy.Developer
is_firewall_gatewayMarks the key as a gateway-scoped token — required to call the MCP dispatch and evaluate-hook routes. A regular key gets 403 on those routes. Reading a gateway key’s plaintext requires Admin.Admin (to enable and to read plaintext)
Keys are masked on display in the console. Plaintext is shown once at creation; gateway-scoped keys require Admin to retrieve it again.

​
3. Policy resolution order

For any request, OrcaRouter resolves the active guardrail and firewall policy independently:
  1. Key attachment — if the key has an explicit guardrail_id (or firewall_policy_id) and that policy exists and is enabled, it applies.
  2. Workspace default — if the key has no attachment, the workspace’s enabled is_default guardrail (or policy) applies.
  3. No enforcement — if neither is set, the request passes without content screening or tool-call enforcement.
The two planes differ when an attached policy is disabled:
  • A disabled or deleted guardrail attachment means the key gets no guardrail — disabling it is the off switch; it does not fall back to the workspace default.
  • A disabled firewall attachment falls back to the workspace default firewall policy — so disabling a firewall attachment reverts the key to the workspace default, it doesn’t turn enforcement off.
A missing (0/unset) attachment always falls back to the workspace default; neither set means no enforcement.
At most one guardrail and one firewall policy per workspace can be the default at any time. Promoting a new default demotes the old one in the same transaction — you can never accidentally have two defaults.

​
4. Least-agency keys — one key per agent

The safest configuration is to give each agent its own narrowly-scoped key rather than sharing a single workspace key across all callers. A well-scoped key for an agent that only calls one model and runs scheduled tasks might look like:
  • model_limits: ["openai/gpt-4o-mini"] — the agent cannot switch to a more expensive or more capable model.
  • allow_ips: the scheduler’s egress CIDR — no other source can present this key.
  • credit_limit_usd: a weekly budget ceiling — a runaway loop cannot exhaust your workspace balance.
  • expired_time: the end of the sprint or deployment lifecycle — the key expires automatically and cannot be reused.
  • guardrail_id: a guardrail specific to this agent’s data sensitivity — tighter than the workspace default.
  • firewall_policy_id: a policy that allow-lists only the tools this agent legitimately needs.
When this agent is compromised via prompt injection, the blast radius is bounded: it can only call one model, only from one IP range, only up to its spend cap, and only the tools its firewall policy permits. The rest of the workspace is unaffected.
Create gateway-scoped keys (is_firewall_gateway) only for the MCP-dispatch or evaluate-hook surface — never for general inference traffic. A gateway key on the inference path gives the caller access to /api/v1/firewall/* routes, which is a broader capability than it needs. One key, one purpose.

​
5. Where policies are authored

Guardrails and firewall policies are both workspace-scoped and shared across all members, but changes require the right role:
  • Read any guardrail, policy, or key — any workspace member.
  • Create or change guardrails, firewall policies, MCP servers, autonomy levels, approval actions, and ordinary API keys — Developer+.
  • Enable is_firewall_gateway on a key; read a gateway key’s plaintext — Admin+.
The workspace is the collaboration boundary: everyone can see the policy catalog; only Developers and above can change it; only Admins can issue gateway credentials.

​
6. Next steps

Secure Agents Baseline

The recommended starting posture — one autonomy-level switch, then tune from real traffic.

Get an API key

Create your first key and attach a guardrail or firewall policy in the console.
Scope is the foundation of the control stack. The narrower each key’s scope, the smaller the blast radius if any one agent is compromised — and the clearer the audit trail that shows what each agent was authorized to do.