# Replacing OpenRouter management keys: a scoped rollout checklist

URL: https://infro.io/blog/replacing-openrouter-management-keys-a-scoped-rollout-checklist
Author: INFRO Editorial (https://infro.io/blog/editorial)
Publisher: INFRO
Published: 2026-11-19
Last modified: 2026-11-19
Last reviewed: 2026-11-19 (next review due 2026-12-19)
Topic: Security and governance
Format: Checklist

> Since 16 November 2026 an OpenRouter management key has two fixed settings, scope (organization or one workspace) and access level (read only or read/write) [^or-announcement]. Replace each broad key with the narrowest pair its job needs, test that the refusals happen, and keep the key list, the test output and the owner sign-off as review evidence.

Key takeaways:
- Scope and access level are both fixed at creation, so every change of privilege means a new key and a deleted old one.
- A read-only key can run every read its scope allows, including analytics queries, and any write returns 403; guardrail policy assignment reads are the documented exception.
- A workspace-scoped key cannot list workspaces, set budgets, or manage organization members, but a read/write one can still create keys, BYOK entries and observability destinations in its workspace.
- Workspace-scoped activity and analytics exclude legacy rows with no workspace, so a per-workspace reporting key may not sum to the organization total.
- Evidence for a review is the key list, a probe that shows the expected 403s, and the owner and expiry of each key; the API key audit endpoint does not list management keys.

## 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](https://infro.io/blog/provider-admin-key-least-privilege).

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 |

Table: the four combinations OpenRouter describes for scope and access level.

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_all` permission 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.

1. **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]
2. **Store the secret where only that job can read it.** The key is shown once; you cannot see it again.[2]
3. **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.
4. **Move provisioning next,** per workspace, to a workspace-scoped read/write key created by that workspace's admin.
5. **Delete the old key** only after its last-use timestamp has stopped moving. Deleting is permanent, so confirm with the owner first.
6. **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]

```python
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](https://infro.io/blog/ai-access-review-checklist-evidence-to-export-for-model-keys).

## 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.

> **Note: What this checklist does not settle**
> OpenRouter's pages describe what each key kind can call. They do not tell you whether a read-only key can read the secret value of a BYOK entry, or how the audit trail records each management call. Ask OpenRouter or test in a non-production workspace before you write either claim into an attestation.

## Questions

### Can a management key make inference calls?

No. OpenRouter states that management keys cannot be used for completion endpoints and are exclusively for administrative operations [2]. Narrowing one limits administration, not model traffic.

### Can I change a key's scope or expiry after creating it?

No. Scope, access level and expiration are fixed at creation; to change any of them you create a new key and delete the old one [2].

## Sources

1. Tighter Access Controls for Management Keys — OpenRouter. https://openrouter.ai/blog/announcements/scoped-management-keys/ (accessed 2026-11-19)
2. Management API Keys — OpenRouter. https://openrouter.ai/docs/guides/overview/auth/management-api-keys (accessed 2026-11-19)
3. API Key Audit — OpenRouter. https://openrouter.ai/docs/cookbook/administration/api-key-audit (accessed 2026-11-19)
4. Security settings — OpenRouter. https://openrouter.ai/docs/guides/overview/auth/security-settings (accessed 2026-11-19)
5. Credential inventory — INFRO. https://infro.io/docs/security/credentials (accessed 2026-11-19)
6. Management tokens — INFRO. https://infro.io/docs/manage/tokens (accessed 2026-11-19)
