Skip to main content
When an agent is compromised — prompt injection, a poisoned tool result, a runaway loop — the damage it can do is bounded by exactly one thing: what its API key was allowed to do. A workspace key shared across every caller turns one compromised agent into a workspace-wide incident. A narrowly scoped key turns the same compromise into a contained, auditable event. This is the hub for the keys section. It covers the least-agency identity model and the fields that scope a key, then links to the focused pages for each one.

​
1. Why scoped api keys for llm agents

A general API key is a bearer credential: whoever holds it can call any model, from anywhere, for any amount, with no policy attached. That is the opposite of what an autonomous agent needs. On OrcaRouter, an API key is not just a credential — it is a scope declaration. Each key carries its own constraints (which models, which IPs, how much spend, when it expires) and points to the guardrail and firewall policy that govern its traffic. Editing the policy a key points to takes effect on the next request, with no redeploy and no agent-code change. The principle is least agency: give each agent the narrowest identity that still lets it do its job, and nothing more. One key, one agent, one purpose.
The fastest way to internalize the model: read Scope & keys for the workspace → policy → key hierarchy, then work the least-agency checklist against a real key.

​
2. What a scoped key carries

Every key is a bundle of limits plus two policy attachments. Each field is documented on its own page — the spoke links below go to the depth.

Model limits

model_limits restricts a key to a named list of models. A call outside the list is rejected before it leaves the gateway — the agent can’t switch to a pricier or more capable model.

IP allow-list

allow_ips pins a key to specific source addresses. A leaked key presented from anywhere else is rejected at the auth layer.

Quota, cap & expiry

credit_limit_usd caps lifetime spend (0 = unlimited); expired_time sets an absolute expiry (-1 = never).

Environments

environment is a freeform label (prod, staging, dev) for organizing keys and filtering logs.

Bind policies

guardrail_id and firewall_policy_id attach a content policy and a tool-call policy to the key. No attachment falls back to the workspace default.

The token object

The full field-by-field reference for a key, including remain_quota / used_quota and is_firewall_gateway.
Bounded vs unbounded. A key with credit_limit_usd: 0 and expired_time: -1 has no spend cap and never expires — convenient, but the worst blast radius if it leaks. See unlimited vs bounded for when each is appropriate.

​
3. One concrete least-agency key

A scheduled agent that summarizes support tickets with one cheap model and runs from one host needs almost no agency. A well-scoped key for it:
FieldValueWhy
model_limitsone summarization modelcan’t escalate to a frontier model
allow_ipsthe scheduler’s egress CIDRa leaked key is useless elsewhere
credit_limit_usda weekly ceilinga runaway loop can’t drain the balance
expired_timeend of the deploymentauto-expires, can’t linger
guardrail_ida PII-masking guardrailrequest text is screened
firewall_policy_idallow-lists only the tools it needsno surprise tool calls
If this agent is hijacked, it can still only call one model, only from one IP range, only up to its cap, and only the tools its firewall policy permits. The rest of the workspace is untouched — and the audit trail shows exactly what it was authorized to do.
Set every field in the key editor in the console (/console/token). Creating or editing keys requires the Developer role or above.

​
4. Binding the two policy planes

The two attachments are the most powerful fields on a key, and they resolve differently when an attached policy is disabled:
Screens the request and response text (PII, secrets, prompt injection) against a workspace-scoped, ordered guardrail. Resolution: an explicit, enabled guardrail_id applies; a disabled one is the off switch — it does not fall back to the workspace default. With no attachment, the workspace default guardrail applies, else nothing.
Governs the actions an agent takes — tool calls, MCP dispatches, egress — against a workspace-scoped firewall policy. Resolution differs from guardrails: a disabled attached firewall policy falls back to the workspace default, it does not turn enforcement off.
A gateway-scoped token is minted only for the Firewall MCP and evaluate-hook routes (/api/v1/firewall/*), never for inference. A regular key gets 403 there. Enabling this flag, and reading the gateway key’s plaintext, requires Admin+.
The full resolution order — key attachment → workspace default → none — lives on Scope & keys and Bind policies.

​
5. The keys section

Manage keys

Create, edit, and revoke keys in the console.

Rotation

Roll a key without downtime.

Expiring keys

Short-lived keys for ephemeral agents and CI runs.

Key masking

Keys are masked on display; plaintext is shown once at creation.

Leaked key

What to do the moment a key is exposed.

Least-agency checklist

Run every key through the same hardening pass.

​
6. Where keys sit in the control stack

A scoped key is the first layer of defense — it decides who the caller is and what it may reach before any policy runs. Guardrails and the Firewall are the next layers.

Securing AI agents

Why agent identity is the foundation of the control stack.

Guardrails vs Firewall

The two policy planes a key can bind to.

Excessive agency

The threat least-agency keys are built to contain.
A key with no model_limits, no allow_ips, no credit_limit_usd, no expiry, and no policy attachment has maximum agency. If it leaks, the holder gets your full workspace. Scope every production key before it ships — start with the secure-agents baseline.
Scope is the foundation: the narrower each key, the smaller the blast radius if any one agent is compromised — and the clearer the record of what each agent was authorized to do.