Skip to main content
A long-lived credential is a liability that grows quietly: the agent gets decommissioned, the demo ends, the contractor moves on — but the key keeps working until someone remembers to revoke it. An expiring api key flips that default. You set an end date when you mint the key, and OrcaRouter stops authorizing it the moment that date passes — no cleanup task to forget, no leaked-but-still-live window. Expiry is one field on the token object: expired_time. This page is the focused guide to that one control. For the spend-cap side of the same screen, see Quota cap & expiry.

​
1. Why set an expiring api key

The point of a time-bound key is to make the safe outcome the default one. A few cases where it pays off:

Ephemeral agents

A scheduled job or short-lived agent gets a key that dies with the deployment lifecycle. A forgotten cron task can’t keep spending months later.

Demos & trials

Hand a prospect a key that works for the length of the evaluation and then goes dark on its own — no follow-up revoke needed.

Contractors & vendors

Scope a credential to the engagement window. When the contract ends, so does the key.

Incident-scoped access

Grant a narrow, short-lived key during an incident so elevated access can’t outlive the incident itself.
Expiry pairs naturally with the rest of a least-agency key — a model allow-list, an IP allow-list, and a spend cap. Each one bounds a different axis; together they keep a compromised key’s blast radius small. See the Least-agency checklist.

​
2. The expired_time field

A key’s expiry lives in a single field on the token object:
FieldTypeMeaning
expired_timeUnix timestamp (seconds)The absolute instant the key stops authorizing. -1 means never expires.
Two things to keep in mind:
  • expired_time is absolute, not a duration. You set the moment the key dies, not “30 days from now” — the console date picker computes the timestamp for you.
  • The default for a new key is -1 (never). A key only expires if you give it a real timestamp; leaving the field untouched mints a non-expiring key.
A non-expiring key (expired_time = -1) is the right choice only for a credential you actively rotate. If you can name the date a key should stop working — and for agents, demos, and contractors you usually can — set it. An unattended -1 key is the one most likely to outlive its purpose.

​
3. Set an expiry in the console

Setting an expiry is a console action on your session / access token — not something you pass on a relay call. Creating or editing a key requires the Developer role or above.
  1. Open Keys (/console/token) and create a new key, or edit an existing one.
  2. In the expiry field, pick the date and time the key should stop working. Leave it blank (or set never) to keep the key permanent.
  3. Save. The change takes effect immediately — no redeploy, no agent-code change.
Editing the expiry on an existing key is live: extend a key that’s about to lapse, or pull its expiry forward to retire it sooner, and the new deadline applies on the next request.
Only /v1/* relay calls carry the sk-orca-… key. The expiry you set here governs that relay key, but you configure it from the console session, never by sending the relay key to a management route.

​
4. What an expired key does

When a key is presented after its expired_time has passed, the gateway rejects it at the auth layer — the request never reaches a model, so it costs no quota. The key’s status moves to Expired, one of the automatic end-states a key can reach:
StatusReached how
EnabledActive; requests are authorized.
DisabledYou paused it; reversible.
ExpiredPast its expired_time — reached automatically.
ExhaustedOver its quota / spend cap — reached automatically.
Expired is terminal in the sense that the key won’t authorize again on its own. If you need it back, edit the key to push expired_time into the future (Developer+) and it returns to Enabled on the next request — the key, its limits, and its policy attachments are all preserved. To retire a key for good instead, revoke it.
Expiry vs. disable vs. revoke. Expiry is the scheduled off switch — you decide the deadline up front and walk away. Disable is the manual, reversible pause for an incident. Revoke (delete) is permanent. Reach for expiry whenever you already know when a credential should stop mattering.

​
5. A worked example: a two-week demo key

Suppose you’re giving a prospect a key for a 14-day evaluation. You want it to call one cheap model, spend no more than a fixed budget, and go dark when the trial ends — all without a calendar reminder to revoke it. In the New key dialog, set:
  • model_limits: ["openai/gpt-4o-mini"] — the demo can’t reach for a pricier model.
  • credit_limit_usd: a fixed trial budget — a runaway loop can’t overrun it.
  • expired_time: the end of the 14-day window — the key stops authorizing on its own when the trial is over.
After the deadline, any further request on this key is rejected with no quota spent, and the key shows Expired in the list. Nothing for you to clean up; the credential retired itself. 
# Before expiry — authorized
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":"ping"}]}'

# After expiry — the same call is rejected at the auth layer,
# the model is never invoked, and no quota is consumed.

​
6. Who can do what

Expiry is governed by the same role gate as the rest of a key’s lifecycle, scoped to your active workspace:
ActionMinimum role
View a key’s expiryViewer
Set or change expired_time (create / edit a key)Developer
Re-reveal an ordinary key’s plaintextDeveloper
Read a gateway-scoped (is_firewall_gateway) key’s plaintextAdmin
For the full lifecycle — create, disable, revoke — and the rotation pattern that pairs with expiry, see Manage keys.

​
7. Next steps

Quota cap & expiry

The spend-cap sibling of expiry — bound a key by dollars as well as by time.

Key rotation

The zero-downtime handoff that keeps a non-expiring key from living forever.

The token object

Every field a key carries, including expired_time, and what each one constrains.

Least-agency checklist

Combine expiry with model limits, IP allow-lists, and spend caps for a minimal-blast-radius key.
A key that knows when to stop is one fewer credential you have to remember to retire. Set expired_time whenever you can name the date — and let the gateway do the cleanup for you.