Skip to main content
You almost never run one key. A real workspace has a production key, a staging key, a developer’s local key, maybe a one-off for a load test — all calling the same models through the same gateway. Tell them apart with the environment tag: a short freeform label you stamp on each key so the console, your team, and the Usage Tracking tab can group keys by where they run. This is the small organizational field, not an enforcement one — it doesn’t change what a key can do. For the limits that bound a key (models, IPs, spend, expiry, policies) start at the scoped keys overview.

​
1. Why the api key environments tag

When every key looks like sk-orca-•••• in the list, you can’t tell the production key from a throwaway dev key — and that’s exactly the key you don’t want to rotate, revoke, or raise a spend cap on by mistake. The environment tag turns an anonymous credential into a labeled one:
  • At a glance — the key list shows which keys are prod, staging, or dev, so you act on the right one.
  • By spend — the Usage Tracking tab can fold spend by environment, so “what is staging costing us this week” is one filter, not a spreadsheet.
  • By convention — a shared vocabulary (prod / staging / dev) across the workspace, so a teammate reading the list understands your layout without asking.
The tag is freeform and descriptive only. It does not gate models, IPs, spend, or policy — those are the other key fields. Two keys tagged prod get no special treatment beyond sharing a label.

​
2. What the field accepts

environment is an optional, short text label on the key object:
PropertyBehavior
TypeFreeform string — no fixed enum. prod, staging, dev are conventions, not built-in values.
LengthTrimmed of surrounding whitespace and clamped to 32 characters; anything longer is truncated.
Empty / unsetA key with no tag reads back as the unlabeled state and folds into an unlabeled segment in Usage Tracking.
Effect on trafficNone — purely organizational.
Pick a small, stable vocabulary and stick to it. prod, staging, dev is enough for most teams; consistency is what makes the tag useful when you filter spend. A free-text field with prod, Prod, and production in it defeats the purpose.

​
3. Set the tag on a key

Set environment in the key editor in the console (/console/token) — the same place you set model limits and policy attachments. Creating or editing keys requires the Developer role or above.
1

Open the key

In the console go to Keys (/console/token) and create a new key or edit an existing one.
2

Set the environment label

Enter a short label — e.g. prod — in the Environment field. Keep it under 32 characters.
3

Save

The tag is now attached to the key. It appears in the key list and becomes available as a Usage Tracking dimension.
Editing a key to change an unrelated field (a rename, a new spend cap) preserves the existing environment tag — the tag is only changed when you explicitly set it. To clear a tag, set the field to an empty value; that’s an intentional reset back to the unlabeled state.

​
4. Segment spend by environment

Once your keys are tagged, the Usage Tracking tab (console → Overview) can group spend, requests, and tokens by the environment dimension. It folds every key’s usage under its environment label, with untagged keys collected under unlabeled. That answers questions the per-key view can’t, at the level you actually budget:
  • How much is staging spending versus prod this week?
  • Did the new dev key blow past what we expected?
  • Which environment drove the spike on Tuesday?
The same view also segments by key, model, member, and use-case task — environment is the one that maps to where the traffic ran. Spend segmentation reads consume rows only, scoped to your workspace, so the numbers line up with Billing.
The environment dimension reads the current label on each key when you load the report. Retagging a key changes how its historical spend folds the next time you open the view — the tag is a live property of the key, not a stamp frozen onto past requests.

​
5. A worked example: three keys, one workspace

A small team running one product across three environments:
KeyenvironmentOther scope (the part that actually enforces)
Production agentprodtight firewall_policy_id, weekly credit_limit_usd, pinned allow_ips
Staging agentstaginga permissive firewall policy in shadow mode, a lower cap
Local devdevmodel_limits to one cheap model, near-term expired_time
The tags don’t change any of those limits — they make the three keys legible. The list reads at a glance, the Usage tab shows three spend bars instead of three opaque key ids, and when you rotate the prod key you’re certain you grabbed the right one.
Pair the environment tag with real enforcement so each key is both labeled and bounded. The tag tells you what a key is; the least-agency checklist makes sure it can’t do more than that environment needs.

​
6. Tags vs. enforcement — don’t confuse the two

The environment tag is the lightest field on a key. It’s easy to reach for it as a security control; it isn’t one. If you want a dev key to be unable to hit production models or spend real money, the label won’t do that — the enforcing fields will:

Model limits

model_limits is what actually stops a dev key from calling a frontier model — not the dev tag.

Quota, cap & expiry

credit_limit_usd and expired_time bound spend and lifetime. The tag organizes; these constrain.

Bind policies

guardrail_id and firewall_policy_id attach the content and tool-call policies that govern the key’s traffic.

The token object

The full field-by-field reference for a key, environment tag included.

​
7. Where this fits

The environment tag is one slice of the broader key model — narrow, labeled identities for every agent and every place it runs.

Scoped keys overview

The hub for every field a key carries.

Scope & keys

How workspaces, policies, and keys nest together.

Manage keys

Create, edit, and revoke keys in the console.
A tag is the cheapest investment in a tidy workspace: a few characters per key, and the difference between a list you can read and one you can’t. Stamp every key with its environment the moment you create it — and let the other fields do the enforcing.