Skip to main content
A key with no source restriction is a pure bearer credential: whoever holds the string can present it from anywhere. The allow_ips field turns a key into an ip whitelist api key — it only works when presented from a source address you listed. A leaked key replayed from an attacker’s box, a residential proxy, or a compromised CI runner is rejected before it touches a model. This is the source-binding half of least agency: model_limits caps which models a key may reach, and allow_ips caps where the key may be presented from.

​
1. What allow_ips does

allow_ips holds a list of source addresses or CIDR ranges. On every request, OrcaRouter compares the caller’s source IP against that list:
  • Match → the request proceeds to model-limit, quota, and policy checks.
  • No match → the request is rejected at the auth layer with HTTP 403 (access_denied), before any upstream model call.
  • Empty list → no restriction; the key is accepted from any address.
The check is the first gate a key passes, alongside key validity — it runs before guardrails, before the firewall, before metering. An unlisted source never reaches your policies or your balance.
An empty allow_ips means all IPs allowed, not none. Leaving it blank is the unrestricted default — pin the key to make the field do anything.

​
2. Accepted formats

Each entry is a single IP or a CIDR range. Mix both freely; list one entry per line.

Single address

203.0.113.7 — exactly one host. Best for a fixed-IP server or a NAT gateway with a stable egress address.

CIDR range

203.0.113.0/24 — a whole block. Best for a cloud subnet, a VPN pool, or an autoscaling group behind one egress CIDR.
A bare IP matches that one address; a CIDR matches every address in the block. Both IPv4 and IPv6 literals parse.
Pin to the narrowest range that still covers every legitimate caller. One host (/32) is tighter than a /24; a /24 is tighter than “anywhere”. Each bit you drop widens the set of places a leaked key still works.

​
3. Set it in the console

Set allow_ips in the key editor at /console/token. Creating or editing a key requires the Developer role or above.
  1. Open Console → API Keys and create or edit a key.
  2. In the key editor, enter your trusted addresses in the IP allow-list field — one IP or CIDR per line.
  3. Save. The restriction applies on the next request that key makes — no redeploy, no agent-code change.
Verify the real source address the gateway sees before you lock a key down. If your agent sits behind a NAT, a load balancer, or an egress proxy, the address OrcaRouter observes is that egress hop — not the agent’s private IP. Allow-list the egress address, and test from the deployed environment before you ship.

​
4. One concrete example: a scheduled agent

A scheduled job that summarizes tickets runs only from one cloud subnet. Pin its key to that subnet so the credential is useless anywhere else.
FieldValueEffect
allow_ips203.0.113.0/24only the scheduler’s egress block can present this key
model_limitsone summarization modelcan’t escalate to a frontier model
credit_limit_usda weekly ceilinga runaway loop can’t drain the balance
The relay call itself is unchanged — it still uses the sk-orca-… key as a bearer token: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Summarize this ticket..."}]
  }'
Presented from inside 203.0.113.0/24, the call proceeds. Replay the exact same request from any other address and the gateway returns: 
{
  "error": {
    "message": "您的 IP 不在令牌允许访问的列表中 (request id: ...)",
    "type": "orcarouter_api_error",
    "code": "access_denied"
  }
}
The model is never called, no quota is spent, and the rejection is logged.
allow_ips is configured entirely through the console key editor — a Developer-or-above action on your workspace session. There is no relay-key self-service for it: a key can’t widen its own source allow-list.

​
5. What an IP allow-list does and doesn’t contain

An ip whitelist api key bounds where a key works — one slice of the blast radius. It composes with the other scope fields rather than replacing them.
A credential exfiltrated from logs, a git commit, or a breached laptop is dead weight unless the attacker can also originate traffic from your allow-listed range. This is the field’s core job — see leaked key for the full incident response.
If the compromise is an allow-listed host — a poisoned dependency running on your own server — the source IP check passes. Pair allow_ips with model_limits, a spend cap, and a firewall policy so a trusted-source compromise is still bounded.
An IP pin doesn’t make a key short-lived. Combine it with an absolute expiry and a rotation schedule so a key both stops working from new places and stops working eventually.

​
6. Operating notes

If your callers don’t have a stable source address (serverless with rotating egress, mobile clients, broad office networks), an IP pin is the wrong control — you’d either lock out real traffic or widen the range until it’s meaningless. Lean on model_limits, spend caps, expiry, and policy attachments instead.
Editing allow_ips takes effect on the next request — there’s no propagation delay to wait out. When you add a region or migrate a subnet, update the key first, confirm the new range works, then drop the old one.
allow_ips lives on the individual key, so each agent can have its own source binding. A scheduler key can pin to a batch subnet while an interactive key allows a broader office range — both in the same workspace.

​
7. Next steps

The token object

Every field on a key, including allow_ips, in one reference.

Model limits

Cap which models a key may reach — the other half of source + scope binding.

Leaked key

What to do the moment a key is exposed.

Least-agency checklist

Run every key through the same hardening pass.
An IP allow-list is the cheapest blast-radius cut you can make: one field, no code change, and a leaked key stops working from everywhere it wasn’t meant to run. Pair it with the rest of the scoped-key model for defense in depth.