Skip to main content
Every long-lived credential should be replaced on a schedule, and immediately on any hint of exposure. The safe way to rotate api key credentials is never to mutate a live key in place — it’s to mint a fresh one, move traffic onto it, and retire the old one once nothing depends on it. Done in that order there’s never a moment with no working key. This page is the step-by-step playbook. For the wider key lifecycle (create / disable / delete) see Manage keys; for every field a key carries see The token object.
All console actions here live in the Keys screen (/console/token) and run on your session / access token — not the relay key. Creating, editing, disabling, or deleting a key requires the Developer role or above. Only /v1/* inference calls use the sk-orca-… relay key.

​
1. Why rotate, and why never in place

A key on OrcaRouter is an immutable identity, not just a string — it carries its own model allow-list, IP allow-list, spend cap, expiry, and policy attachments. You cannot change the secret material of an existing key; the credential and the constraints are issued together at creation. So “rotating” means issuing a successor and migrating onto it. Do it:
  • on a fixed cadence for any production credential (quarterly is a common baseline);
  • the moment a key is suspected leaked — though for a confirmed leak, cut it off first and rotate second (see Leaked key response);
  • whenever the key’s owner (an employee, a vendor integration, a decommissioned agent) changes.
The plaintext (sk-orca-…) is shown once, at creation — copy it then. Afterward the console shows only a masked form like orca-7Bf****wxyz. A Developer+ can re-reveal an ordinary key’s plaintext later, but a gateway-scoped key (is_firewall_gateway) requires Admin to read its plaintext again — so treat the gateway key’s first reveal as your only reliable copy.

​
2. The rotate api key sequence

The whole point is a clean overlap: the new key works before the old one stops. Four steps.
1

Create the successor key

Mint a new key with the same scope as the one you’re replacing — the same model_limits, allow_ips, credit_limit_usd, expired_time, and the same guardrail_id / firewall_policy_id. Copy the plaintext immediately. Rotation is the ideal moment to tighten scope too: drop a model the agent no longer uses, or narrow the IP allow-list.
2

Migrate traffic

Deploy the new sk-orca-… to every caller — config, secret manager, CI variable, agent runtime. Roll it out the same way you ship any secret change. Both keys are live at this point, so deployments can be staggered without an outage.
3

Verify the new key is carrying load

Confirm the successor is actually serving traffic before you touch the old one. Watch the new key’s used_quota climb while the old key’s flattens — the per-key usage is your cutover signal.
4

Retire the old key

Once the old key shows no traffic, disable it first (reversible) and watch for stragglers, then delete it for good. Disable is the pause; delete is the point of no return.
Set an environment label on each key — reuse it across the old and new key, or bump it (prod → prod-2026q2) — so the successor and predecessor are labelled distinctly while both are live during the overlap window.

​
3. A concrete rotation, via REST

Everything below is a console action — these management routes run under your session (UserAuth), not the relay key. Suppose you’re replacing the key for a scheduled summarizer agent. Create the successor with the same scope: 
# Console session token — NOT an sk-orca-… relay key
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
The response returns the plaintext once ("data": "sk-orca-…"). Copy it, deploy it to the summarizer, and confirm the new key is serving before moving on. When the old key (id 481) shows no traffic, disable then delete it: 
# Pause first (reversible) — set the old key's status to Disabled (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Once you're sure nothing depends on it — revoke for good
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
A key’s status is one of Enabled (1), Disabled (2), Expired (3), or Exhausted (4). Disabling sets it to Disabled; every request the key makes is then rejected while its config, attachments, and history stay intact. Deleting is permanent — the credential can never authorize a request again, and a deleted key is not recoverable.
You can do all of this without the API — the Keys screen has New key, a per-key Disabled toggle, and Delete (single or batch). The REST form above is for scripting scheduled rotations.

​
4. Rotating policy-bound and gateway keys

A key’s guardrail and firewall attachments live on the key, so the successor must carry the same guardrail_id and firewall_policy_id to enforce the same posture. Two things to know:
Guardrails and firewall policies are workspace-scoped, named resources shared across keys. Rotating a key doesn’t touch the policy itself; you’re just re-pointing a fresh key at the existing guardrail_id / firewall_policy_id. The policy keeps governing traffic uninterrupted.
A key with is_firewall_gateway set drives the Firewall gateway routes (/api/v1/firewall/*). Minting one, and re-revealing its plaintext, both require Admin. Because you can’t casually re-read its secret, capture the new gateway key’s plaintext at creation and store it in your secret manager before you cut over.
Don’t reuse a single key — gateway or otherwise — across many agents and “rotate” by editing limits. One key per agent keeps each rotation isolated and the blast radius small. See the Least-agency checklist.

​
5. Emergency rotation (suspected leak)

If you think a key is exposed, the order flips: stop the bleeding first, migrate second.
  1. Disable the suspect key right away so it can’t authorize anything while you investigate — or delete it outright if the leak is confirmed.
  2. Mint the successor and roll it out as in §2.
  3. Review what the leaked key did before you cut it: filter the request logs by that key (token) to scope the blast radius.
The full incident runbook is on Leaked key response.
A short expired_time is rotation insurance: an expiring key retires itself even if you forget the manual rotation, capping how long any single credential can ever be abused.

​
6. Next steps

Manage keys

The create / disable / revoke lifecycle these steps build on.

Bind policies to a key

Carry the same guardrail and firewall policy onto the successor.

Expiring keys

Set an expiry so keys rotate themselves on a deadline.

Leaked key response

The emergency path when a credential is exposed.
Rotation is just disciplined overlap: a successor that works before the predecessor stops. Keep each key narrowly scoped and the handoff stays boring — which is exactly what you want from a credential rotation.