Skip to main content
You have a saved guardrail and you want a specific API key screened by it — not the whole workspace. That is what the guardrail per API key binding is for: set guardrail_id on the key and every /v1/* call made with that key is screened on the next request, with no redeploy and no SDK change. This page covers only the binding — how to attach, how resolution picks the effective policy, and what the off-switch does. For the rule types, actions, and stages, see the Guardrails reference.

​
1. Bind a guardrail per API key with guardrail_id

A guardrail is workspace-scoped, but enforcement is decided per key. Each API key carries a guardrail_id field. Point it at a guardrail and that key — and only that key — is screened by that policy. This lets one workspace run different policies on different keys:
  • a production key bound to a strict pii-blocker,
  • a staging key bound to a lighter flag-only policy,
  • an internal key with nothing attached.
The binding lives on the key in the gateway, so editing the guardrail shifts the bound key on its next request. Your application keeps calling https://api.orcarouter.ai/v1/chat/completions exactly as before.
The relay key (sk-orca-…) is what your app sends. Attaching a guardrail to it is a console / token-API action authenticated by your session — you never configure a guardrail with the relay key itself.

​
2. Attach it in the console

Configure the binding from the console (role-gated: editing keys and guardrails requires Developer+).
1

Open the key

Go to /console/token and create or edit the API key you want screened.
2

Pick the guardrail

In the key editor, choose your guardrail from the Guardrail dropdown. This sets guardrail_id on the key.
3

Save

The binding takes effect on that key’s next request. No redeploy.
After that, a normal relay call with the bound key is screened automatically: 
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": "Reply to jane@acme.com please"}
    ]
  }'
If the bound guardrail masks email at the input stage, the upstream model sees [EMAIL] and never the address — same call, no client change.
To screen every key in the workspace instead of one, set the guardrail as the workspace default rather than binding each key. See Account default guardrail.

​
3. How resolution picks the effective guardrail

On every request, the gateway resolves exactly one effective guardrail (or none) in this order:
If the key’s guardrail_id points at a guardrail and that guardrail exists and is enabled, it applies. An explicit attachment is authoritative — it never silently falls back to the workspace default.
If the key has no attachment (guardrail_id is 0 / unset), the workspace’s enabled default guardrail applies, if one is set.
No enforcement. The request is byte-identical to a workspace that never enabled the feature — nothing blocked, masked, or logged.
The decision is one indexed lookup on the hot path and is fail-open: if resolution hits a transient error, the gateway degrades to no enforcement rather than failing the request. Safety degrades; availability is preserved.

​
4. The off-switch: disable an attachment, no fallback

This is the part people miss. An explicit key attachment is its own authority — so disabling the attached guardrail turns enforcement OFF for that key, and it does not fall back to the workspace default.
Key stateWhat screens the request
guardrail_id → enabled guardrailthat guardrail
guardrail_id → disabled guardrailnothing (no fallback)
guardrail_id → deleted / missingnothing (no fallback)
guardrail_id = 0 / unsetworkspace default, if any
Disabling an attached guardrail is the off switch for that key, not a downgrade to the default. If you want a key to fall back to the workspace default, clear its attachment (set guardrail_id to 0) — don’t just disable the guardrail it points at.
This is a deliberate difference from the firewall: a key with a disabled attached firewall policy does fall back to the workspace-default firewall policy, whereas a disabled attached guardrail resolves to none. Same idea, opposite fallback — see Guardrails vs. firewall.

​
5. Detach or clear the binding

To stop screening a key with a specific guardrail, you have two distinct moves with different outcomes:
  • Clear the attachment — set the key’s guardrail_id to 0. The key now resolves to the workspace default (if one exists), or to none.
  • Disable the guardrail — flip the guardrail’s enabled off. Every key explicitly attached to it now resolves to none (per §4), while keys that were relying on it as the workspace default fall through to no enforcement.
Pick clear when you want the key on the workspace baseline; pick disable when you want to pause that policy everywhere it is the named attachment.

​
6. What a screened request does (and doesn’t) cost

Once a guardrail resolves, its rules decide the request. The two outcomes worth knowing for a bound key:
  • A block returns HTTP 400 with error code guardrail_blocked, naming the guardrail and the rule that fired. It costs no quota — an input-stage block fires before metering, an output-stage block refunds the pre-consumed quota — and it is marked skip-retry.
  • A mask rewrites the match to a typed tag (e.g. [EMAIL]) and lets the request through sanitized; the upstream model never sees the original.
See the guardrail_blocked error page for the exact response shape, and Streaming coverage for how output rules behave on streamed responses.

​
7. Where to go next

Create your first guardrail

Build the policy you’ll bind to a key.

Account default guardrail

Screen every key in the workspace at once.

Guardrails reference

Rule types, actions, stages, PII, judge, grounding.

Keys, policies & workspaces

How bindings are scoped across the gateway.