Creating a Management API Key
To use the management API, you first need to create a Management API key:- Go to the Management API Keys page
- Click “Create New Key”
- Enter a name and choose an expiration
- Copy the key when it is shown. You will not be able to see it again
Expiration
We recommend setting an expiration date on every management key. A leaked management key could create, edit and delete the API keys in your account other than those provisioned by a Connect client, and one with no expiration stays valid until you delete it.- The expiration is fixed when the key is created and cannot be changed afterwards. To extend access, create a new key and delete the old one.
- Once a key’s expiration passes, every request that uses it fails with
401 Unauthorizedand the messageAPI key expired. Expired keys still appear on the Management API Keys page until you delete them.
Scope
A management key is scoped either to the whole organization or to one workspace.Organization-scoped keys
Organization-scoped keys cover administrative actions across all of the account’s workspaces. For organizations, only Organization Admins can create them, on the Management API Keys page.Workspace-scoped keys
Workspace-scoped keys act only on their own workspace. To create one:- Open the workspace, go to Keys and select the Management keys tab. Workspace Admins of that workspace can create keys here; Organization Admins can create them in any workspace.
- Click “New management key”. The dialog shows which workspace the key is scoped to.
- Enter a name, choose an expiration and an access level.
- Copy the key when it is shown.
workspace_id, it defaults to the key’s own workspace. Naming another workspace, or a resource that belongs to one, is refused.
Every other route in Routes That Require a Management Key needs an organization-scoped key and returns
403 Forbidden to a workspace-scoped key. This includes listing, creating and deleting workspaces, setting and deleting workspace budgets, credits, organization settings and members, SCIM, private endpoints and providers, external users and datasets.
Workspace members
- Programmatic Management: Endpoints for managing workspace members (
POST /api/v1/workspaces/{id}/members/add), keys, and budgets require a Management API key. Members added via the API automatically inherit their organization role (Org Admins become Workspace Admins; Org Members become Workspace Members). - Dashboard UI: Within the OpenRouter dashboard, Workspace Admins can add members on the workspace Members page without requiring a Management API key. Assigning workspace roles there additionally requires a Pro or Enterprise plan.
Permissions
Organizations choose a management key’s access level when creating it, under Access level:- Read/write keys can call every management route their scope allows.
- Read only keys can call every read (
GET, and read-only queries such asPOST /api/v1/analytics/query) that a read/write key of the same scope can call, and nothing else. Any request that would create, change or delete something returns403 Forbidden. One exception:GET /api/v1/guardrails/policies/assignments/members/{member_id}andGET /api/v1/guardrails/policies/assignments/api-keys/{hash}need a read/write key, because reading an assignment creates it if it doesn’t exist yet. - Custom keys use
access_level: "custom"and grant only the actions listed inextra_permissions. At least one action is required; unselected resources grant nothing. On the alpha site, eligible organization and workspace admins can grant access per resource. The picker shows only resources with a grant available in the selected scope. Read & Write includes only the supported actions for that resource, not full management access. Switching to a workspace removes any selected organization-only permissions and lists what was removed.
Use read-only keys for monitoring, reporting and auditing: listing API keys and their usage, reading activity and analytics, checking guardrails, budgets and BYOK credentials, and listing workspaces and their members.
cURL
Errors
Use Cases
Common scenarios for programmatic key management include:- SaaS Applications: Automatically create unique API keys for each customer instance
- Key Rotation: Regularly rotate API keys for security compliance
- Usage Monitoring: Track key usage and automatically disable keys that exceed limits (with optional daily/weekly/monthly limit resets)
Example Usage
All key management endpoints are under/api/v1/keys and require a Management API key in the Authorization header.
Response Format
API responses return JSON objects containing key information:Organization Settings
A management key created in an organization can also read and update that organization’s settings at/api/v1/organization/settings. The organization is the one the key belongs to; it cannot be chosen per request.
Currently exposed setting:
is_filtered_model_catalog_enabled(defaultfalse): the same switch as Settings → Privacy → “Filter the model catalog for API keys”. When enabled,GET /api/v1/modelscalled with one of the organization’s API keys returns only the models that key can use (the/api/v1/models/usercatalog), and the signed-in dashboard shows the same list. Requests without a key still receive the public catalog. Which models remain visible is decided by the active workspace’s guardrails and provider preferences; enabling the switch does not change those.
cURL
404 Not Found from these routes.