What changed on 16 November, and why it matters for your key list
Until this month, an OpenRouter management key always had full read and write access to the whole organization.1 A team that wanted to automate its own workspace had to hold a key that could reach every other workspace too. Now each key carries two settings: scope (one workspace or the whole organization) and access level (read only or read/write).1 The change is available to every organization on every plan.1
If you hold management keys for provisioning scripts and usage reporting, you probably hold them at the old, broadest level. The vendor's own warning explains the stakes: a leaked management key could create, edit and delete the API keys in your account, and one with no expiration stays valid until you delete it.2 This checklist covers the OpenRouter side only. For the vendor-neutral principles, see least privilege for provider admin and usage keys.
Two constraints shape every step below. Management keys cannot call completion endpoints, so narrowing them never touches inference traffic.2 And scope, access level and expiration are all fixed at creation, so there is no "downgrade in place": you create a new key, move the caller, then delete the old one.2
Step 1: Inventory every management key you hold
You cannot replace what you have not listed. The API key audit endpoint will not help here, because it returns standard API keys only; management keys and keys created through OAuth are not included, and OpenRouter says to review those on the Security settings page.3
- Open Security settings, go to Key safety, open Filter keys and select Show management keys; each active key is listed with its owner, last use and expiration.1
- Record, per key: name, owner, scope, access level if shown, expiry, last use, and the job or system that holds the secret.
- Mark keys with no expiry or with a last use older than your threshold. Key safety marks keys idle 90+ days as a category for standard keys; apply the same threshold to management keys yourself.4
- Find the owner of every key. Organization admins can see every key in the organization, while members see only keys they created.4
- For each key, write down what its caller actually does. Read the caller's code or logs rather than the key's name.
The last item decides everything. Most reporting scripts only call GET /api/v1/keys and GET /api/v1/activity. Most provisioning pipelines only create, patch and delete keys in one team's workspace. Neither needs organization-wide write.
Step 2: Map each job to one of four key kinds
OpenRouter's own mapping is a good default:1
| Job | Scope | Access level |
|---|---|---|
| Pipeline that creates and rotates API keys for one team | One workspace | Read/write |
| Usage dashboard for one team | One workspace | Read only |
| Organization-wide audit or cost tool | Organization | Read only |
| Anything that creates workspaces or sets budget limits | Organization | Read/write |
Two rules keep the table honest. First, only the last row should need an organization-scoped read/write key, and you should expect very few of them. Second, who can create each kind differs: only Organization Admins can create organization-scoped keys, while a Workspace Admin can create, list and delete management keys for their own workspace only.2 That makes workspace teams self-serve for their own automation without being able to mint an organization key.
Step 3: Know what each scope can and cannot do
Read the route list before you promise a team that a workspace key is enough. A workspace-scoped key can call only a listed set of routes, only for its own workspace, and naming another workspace or one of its resources is refused.2
Inside a workspace key's reach: API keys, workspace details and members (add and remove), guardrails and guardrail policies, BYOK entries, observability destinations, presets, and read-only access to workspace budgets, activity and analytics.2
Outside it, returned as 403 Forbidden: listing, creating and deleting workspaces, setting and deleting workspace budgets, billing-level routes, organization settings and members, SCIM, private endpoints and providers, external users and datasets.2 Account-level guardrail policies and assigning or unassigning organization members to guardrails also need an organization-scoped key.2
Read this list as an attacker would. A read/write workspace key is not harmless: from the documented routes it can create and delete the workspace's API keys, add and remove workspace members, register BYOK entries, and create observability destinations. That is a reasonable blast radius for a team pipeline, and a poor one for a dashboard, which is why the access level exists. The same list shows what a team cannot do: it cannot raise its own workspace budget.1
Read-only keys: what "read" includes
A read-only key can call every read a read/write key of the same scope can, including read-only queries such as POST /api/v1/analytics/query; anything that would create, change or delete returns 403.2 Two details deserve a line in your runbook:
- Reading a guardrail policy assignment for a member or an API key needs a read/write key, because the read creates the assignment if it does not exist yet.2 An audit script that walks those endpoints will fail on a read-only key; use the list endpoints instead.
- Workspace-scoped activity and analytics need the
activity:view_allpermission on the workspace, and they exclude legacy rows with no workspace, including for the default workspace.2 A per-workspace reporting key can therefore under-count against an organization-wide figure. Reconcile the two once, and decide which one finance treats as the total.
Step 4: Roll out in an order that does not break automation
Expiry is the sharpest failure mode. Once a key's expiration passes, every request using it fails with 401 Unauthorized and the message API key expired, so automations need a new key before the old one lapses.2 Treat replacement as a deploy, not a settings change.
- Start with reporting. Create the read-only key (workspace or organization, per the table), with an expiration you can live with, such as a quarter. OpenRouter recommends an expiration on every management key.2
- Store the secret where only that job can read it. The key is shown once; you cannot see it again.2
- Point the reporting job at the new key and run it side by side with the old one for one reporting cycle. Compare outputs, including the legacy-row gap above.
- Move provisioning next, per workspace, to a workspace-scoped read/write key created by that workspace's admin.
- Delete the old key only after its last-use timestamp has stopped moving. Deleting is permanent, so confirm with the owner first.
- Leave one organization-scoped read/write key, if any, for the work that really needs it: workspace creation and budget limits. Give it the shortest expiry you can operate, and name its owner.
If you also use the IP allowlist, check how it treats your new keys. On the Enterprise plan, a management key scoped to a workspace must match an entry that applies to that workspace, and a management key not scoped to a workspace must match an entry that applies to all workspaces; if no entry applies to all workspaces, unscoped management keys are unrestricted.4 The allowlist is also not checked on endpoints that accept only management keys, such as those that create and manage API keys, workspaces and guardrails.4 Do not count on it to protect those routes.
Step 5: Prove the limits hold
A scope you have not tested is a claim. Run a probe against each new key and keep the output. The error messages are documented: a read-only key that writes, or a key reaching outside its scope, gets 403 with "Management key does not have permission for this request"; a workspace key on an organization route gets a message saying an organization-scoped key is required; and a workspace key naming another workspace gets "Management key is scoped to a different workspace".2
import os, sys, requests
BASE = "https://openrouter.ai/api/v1"
key = os.environ["KEY_UNDER_TEST"]
kind = sys.argv[1] # "ws-read-only" | "ws-read-write" | "org-read-only"
H = {"Authorization": f"Bearer {key}"}
def status(method, path, **kw):
return requests.request(method, BASE + path, headers=H, timeout=15, **kw).status_code
results = {"GET /keys": status("GET", "/keys")} # every kind should allow this read
if kind.endswith("read-only"):
# A write must be refused. If this returns 2xx the key can write:
# delete the key it created (name below) and fail the check.
results["POST /keys"] = status("POST", "/keys", json={"name": "scope-probe-delete-me"})
if kind.startswith("ws-"):
# Listing workspaces is an organization-level route.
results["GET /workspaces"] = status("GET", "/workspaces")
expected = {"GET /keys": 200, "POST /keys": 403, "GET /workspaces": 403}
failed = {k: v for k, v in results.items() if v != expected[k]}
print(results)
sys.exit(1 if failed else 0)Keep the printed result, the date, the key's name and the person who ran it. Run it again after any rotation. The write probe is deliberate: if a key you believed was read-only returns a success, you have found the finding, and the script tells you to remove the key it just created.
Step 6: Keep the evidence for the access review
A reviewer wants to see who holds which authority and that someone looked. Assemble this per review period:
- Export of the management key list from Key safety (owner, last use, expiration), dated.
- The inventory table from step 1, with the scope and access level of each key and the job it serves.
- The probe output from step 5 for every key issued or rotated this period.
- A list of keys deleted since the last review, with the replacement key and the date the caller moved.
- The standard API key audit output (no spend limit, never expires, idle) for every workspace, since those keys are what management keys create and delete.3
- A named owner's sign-off for each organization-scoped read/write key, with the reason it cannot be narrower.
- Any exceptions, such as a key with no expiry, with an end date.
For the standard keys, the audit script lists every workspace and then the keys in each, flagging no spend limit, no expiry and idle keys; because an expiration cannot be added to an existing key, the fix is to replace it.3 The broader question of which evidence an auditor accepts for model keys is covered in the AI access review checklist.
Where INFRO fits, and where it does not
INFRO's Security → Credentials screen lists the INFRO-side credentials that can spend money or change configuration, including gateway keys, provider connections and management tokens, with owner, last use, scope and expiry and a CSV export.5 It does not list OpenRouter's own management keys, which you still review in OpenRouter's settings as above. INFRO's management tokens use the same pattern of narrow, expiring credentials: scopes granted as read or write per family, an expiry, and revocation in the console.6 If you run OpenRouter as one of your provider accounts, keeping both inventories on the same review calendar is the practical benefit.
