Management API Keys

OpenRouter provides endpoints to programmatically manage your API keys, enabling key creation and management for applications that need to distribute or rotate keys automatically.

Creating a Management API Key

To use the key 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

Management keys cannot be used to make API calls to OpenRouter’s completion endpoints - they are exclusively for administrative operations.

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 Unauthorized and the message API key expired. Expired keys still appear on the Management API Keys page until you delete them.

Automations that call the key management API with an expiring management key must be given a new key before the old one expires, or they will start receiving 401 API key expired responses. Schedule rotation ahead of the expiration date shown next to the key.

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.

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: 'your-management-key', // Use your Management API key
});

// List the most recent 100 API keys
const keys = await openRouter.apiKeys.list();

// You can paginate using the offset parameter
const keysPage2 = await openRouter.apiKeys.list({ offset: 100 });

// Create a new API key
const newKey = await openRouter.apiKeys.create({
  name: 'Customer Instance Key',
  limit: 1000, // Optional credit limit
});

// Get a specific key
const keyHash = '<YOUR_KEY_HASH>';
const key = await openRouter.apiKeys.get(keyHash);

// Update a key
const updatedKey = await openRouter.apiKeys.update(keyHash, {
  name: 'Updated Key Name',
  disabled: true, // Optional: Disable the key
  includeByokInLimit: false, // Optional: control BYOK usage in limit
  limitReset: 'daily', // Optional: reset limit every day at midnight UTC
});

// Delete a key
await openRouter.apiKeys.delete(keyHash);

import requests

MANAGEMENT_API_KEY = "your-management-key"
BASE_URL = "https://openrouter.ai/api/v1/keys"

# List the most recent 100 API keys
response = requests.get(
    BASE_URL,
    headers={
        "Authorization": f"Bearer {MANAGEMENT_API_KEY}",
        "Content-Type": "application/json"
    }
)

# You can paginate using the offset parameter
response = requests.get(
    f"{BASE_URL}?offset=100",
    headers={
        "Authorization": f"Bearer {MANAGEMENT_API_KEY}",
        "Content-Type": "application/json"
    }
)

# Create a new API key
response = requests.post(
    f"{BASE_URL}/",
    headers={
        "Authorization": f"Bearer {MANAGEMENT_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Customer Instance Key",
        "limit": 1000  # Optional credit limit
    }
)

# Get a specific key
key_hash = "<YOUR_KEY_HASH>"
response = requests.get(
    f"{BASE_URL}/{key_hash}",
    headers={
        "Authorization": f"Bearer {MANAGEMENT_API_KEY}",
        "Content-Type": "application/json"
    }
)

# Update a key
response = requests.patch(
    f"{BASE_URL}/{key_hash}",
    headers={
        "Authorization": f"Bearer {MANAGEMENT_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Key Name",
        "disabled": True,  # Optional: Disable the key
        "include_byok_in_limit": False,  # Optional: control BYOK usage in limit
        "limit_reset": "daily"  # Optional: reset limit every day at midnight UTC
    }
)

# Delete a key
response = requests.delete(
    f"{BASE_URL}/{key_hash}",
    headers={
        "Authorization": f"Bearer {MANAGEMENT_API_KEY}",
        "Content-Type": "application/json"
    }
)

const MANAGEMENT_API_KEY = 'your-management-key';
const BASE_URL = 'https://openrouter.ai/api/v1/keys';

// List the most recent 100 API keys
const listKeys = await fetch(BASE_URL, {
  headers: {
    Authorization: `Bearer ${MANAGEMENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

// You can paginate using the `offset` query parameter
const listKeys = await fetch(`${BASE_URL}?offset=100`, {
  headers: {
    Authorization: `Bearer ${MANAGEMENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

// Create a new API key
const createKey = await fetch(`${BASE_URL}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${MANAGEMENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Customer Instance Key',
    limit: 1000, // Optional credit limit
  }),
});

// Get a specific key
const keyHash = '<YOUR_KEY_HASH>';
const getKey = await fetch(`${BASE_URL}/${keyHash}`, {
  headers: {
    Authorization: `Bearer ${MANAGEMENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

// Update a key
const updateKey = await fetch(`${BASE_URL}/${keyHash}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${MANAGEMENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Updated Key Name',
    disabled: true, // Optional: Disable the key
    include_byok_in_limit: false, // Optional: control BYOK usage in limit
    limit_reset: 'daily', // Optional: reset limit every day at midnight UTC
  }),
});

// Delete a key
const deleteKey = await fetch(`${BASE_URL}/${keyHash}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${MANAGEMENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

Response Format

API responses return JSON objects containing key information:

{
  "data": [
    {
      "created_at": "2025-02-19T20:52:27.363244+00:00",
      "updated_at": "2025-02-19T21:24:11.708154+00:00",
      "hash": "<YOUR_KEY_HASH>",
      "label": "sk-or-v1-abc...123",
      "name": "Customer Key",
      "disabled": false,
      "limit": 10,
      "limit_remaining": 10,
      "limit_reset": null,
      "include_byok_in_limit": false,
      "usage": 0,
      "usage_daily": 0,
      "usage_weekly": 0,
      "usage_monthly": 0,
      "byok_usage": 0,
      "byok_usage_daily": 0,
      "byok_usage_weekly": 0,
      "byok_usage_monthly": 0
    }
  ]
}

When creating a new key, the response will include the key string itself. Read more in the API reference.

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 (default false): the same switch as Settings → Privacy → “Filter the model catalog for API keys”. When enabled, GET /api/v1/models called with one of the organization’s API keys returns only the models that key can use (the /api/v1/models/user catalog), 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

# Read the current settings
curl https://openrouter.ai/api/v1/organization/settings \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Enable the filtered model catalog
curl -X PATCH https://openrouter.ai/api/v1/organization/settings \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_filtered_model_catalog_enabled": true}'

Both calls return the persisted settings:

{
  "data": {
    "id": "org_2dHFtVWx2n56w6HkM0000000000",
    "is_filtered_model_catalog_enabled": true
  }
}

Management keys created in a personal account receive 404 Not Found from these routes.

Routes That Require a Management Key

The following documented routes reject regular API keys and must be called with a Management API key.

Analytics

Method	Route	Reference
`GET`	`/api/v1/activity`	Get user activity grouped by endpoint
`GET`	`/api/v1/analytics/meta`	Get available analytics metrics and dimensions
`POST`	`/api/v1/analytics/query`	Query analytics data

API Keys

Method	Route	Reference
`GET`	`/api/v1/keys`	List API keys
`POST`	`/api/v1/keys`	Create a new API key
`GET`	`/api/v1/keys/{hash}`	Get a single API key
`DELETE`	`/api/v1/keys/{hash}`	Delete an API key
`PATCH`	`/api/v1/keys/{hash}`	Update an API key

BYOK

Method	Route	Reference
`GET`	`/api/v1/byok`	List BYOK provider credentials
`POST`	`/api/v1/byok`	Create a BYOK provider credential
`GET`	`/api/v1/byok/{id}`	Get a BYOK provider credential
`DELETE`	`/api/v1/byok/{id}`	Delete a BYOK provider credential
`PATCH`	`/api/v1/byok/{id}`	Update a BYOK provider credential

Credits

Method	Route	Reference
`GET`	`/api/v1/credits`	Get remaining credits

End Users

Method	Route	Reference
`GET`	`/api/v1/end-users`	List registered end users
`POST`	`/api/v1/end-users`	Register an end user
`GET`	`/api/v1/end-users/{user}`	Get a registered end user
`DELETE`	`/api/v1/end-users/{user}`	Deactivate a registered end user
`PATCH`	`/api/v1/end-users/{user}`	Update a registered end user

Generations

Method	Route	Reference
`POST`	`/api/v1/generation/feedback`	Submit feedback for a generation

Guardrails

Method	Route	Reference
`GET`	`/api/v1/guardrails`	List guardrails
`POST`	`/api/v1/guardrails`	Create a guardrail
`GET`	`/api/v1/guardrails/{id}`	Get a guardrail
`DELETE`	`/api/v1/guardrails/{id}`	Delete a guardrail
`PATCH`	`/api/v1/guardrails/{id}`	Update a guardrail
`GET`	`/api/v1/guardrails/{id}/assignments/keys`	List key assignments for a guardrail
`POST`	`/api/v1/guardrails/{id}/assignments/keys`	Bulk assign keys to a guardrail
`POST`	`/api/v1/guardrails/{id}/assignments/keys/remove`	Bulk unassign keys from a guardrail
`GET`	`/api/v1/guardrails/{id}/assignments/members`	List member assignments for a guardrail
`POST`	`/api/v1/guardrails/{id}/assignments/members`	Bulk assign members to a guardrail
`POST`	`/api/v1/guardrails/{id}/assignments/members/remove`	Bulk unassign members from a guardrail
`GET`	`/api/v1/guardrails/assignments/keys`	List all key assignments
`GET`	`/api/v1/guardrails/assignments/members`	List all member assignments

Observability

Method	Route	Reference
`GET`	`/api/v1/observability/destinations`	List observability destinations
`POST`	`/api/v1/observability/destinations`	Create an observability destination
`GET`	`/api/v1/observability/destinations/{id}`	Get an observability destination
`DELETE`	`/api/v1/observability/destinations/{id}`	Delete an observability destination
`PATCH`	`/api/v1/observability/destinations/{id}`	Update an observability destination

Organization

Method	Route	Reference
`GET`	`/api/v1/organization/members`	List organization members
`GET`	`/api/v1/organization/settings`	Get organization settings
`PATCH`	`/api/v1/organization/settings`	Update organization settings

Private Endpoints

Method	Route	Reference
`GET`	`/api/v1/private-endpoints`	List private endpoints
`POST`	`/api/v1/private-endpoints`	Create a private endpoint
`GET`	`/api/v1/private-endpoints/{id}`	Get a private endpoint
`DELETE`	`/api/v1/private-endpoints/{id}`	Delete a private endpoint
`PATCH`	`/api/v1/private-endpoints/{id}`	Update a draft private endpoint
`POST`	`/api/v1/private-endpoints/{id}/activate`	Activate a validated private endpoint
`POST`	`/api/v1/private-endpoints/{id}/disable`	Disable a private endpoint
`POST`	`/api/v1/private-endpoints/{id}/enable`	Enable a private endpoint
`PUT`	`/api/v1/private-endpoints/{id}/pricing`	Set private endpoint pricing
`POST`	`/api/v1/private-endpoints/{id}/validate`	Validate a draft private endpoint

SCIM

Method	Route	Reference
`GET`	`/api/v1/scim/group-mappings`	List SCIM group mappings
`POST`	`/api/v1/scim/group-mappings`	Create a SCIM group mapping
`GET`	`/api/v1/scim/group-mappings/{id}`	Get a SCIM group mapping
`DELETE`	`/api/v1/scim/group-mappings/{id}`	Delete a SCIM group mapping
`PATCH`	`/api/v1/scim/group-mappings/{id}`	Update a SCIM group mapping
`GET`	`/api/v1/scim/groups`	List SCIM groups
`POST`	`/api/v1/scim/sync-jobs`	Start a SCIM directory sync
`GET`	`/api/v1/scim/sync-jobs/{id}`	Get SCIM directory sync status

Workspaces

Method	Route	Reference
`GET`	`/api/v1/workspaces`	List workspaces
`POST`	`/api/v1/workspaces`	Create a workspace
`GET`	`/api/v1/workspaces/{id}`	Get a workspace
`DELETE`	`/api/v1/workspaces/{id}`	Delete a workspace
`PATCH`	`/api/v1/workspaces/{id}`	Update a workspace
`GET`	`/api/v1/workspaces/{id}/members`	List workspace members
`POST`	`/api/v1/workspaces/{id}/members/add`	Bulk add members to a workspace
`POST`	`/api/v1/workspaces/{id}/members/remove`	Bulk remove members from a workspace
`GET`	`/api/v1/workspaces/{workspace_ref}/budgets`	List workspace budgets
`GET`	`/api/v1/workspaces/{workspace_ref}/budgets/{interval}`	Get a workspace budget
`PUT`	`/api/v1/workspaces/{workspace_ref}/budgets/{interval}`	Create or update a workspace budget
`DELETE`	`/api/v1/workspaces/{workspace_ref}/budgets/{interval}`	Delete a workspace budget

Overview

Models & Routing

Tool Calling

Features

Observability

Authentication

Ori

Developer Tools

Privacy

Best Practices

Community

Creating a Management API Key

Expiration

Use Cases

Example Usage

Response Format

Organization Settings

Routes That Require a Management Key

Analytics

API Keys

BYOK

Credits

End Users

Generations

Guardrails

Observability

Organization

Private Endpoints

SCIM

Workspaces

​Creating a Management API Key

​Expiration

​Use Cases

​Example Usage

​Response Format

​Organization Settings

​Routes That Require a Management Key

​Analytics

​API Keys

​BYOK

​Credits

​End Users

​Generations

​Guardrails

​Observability

​Organization

​Private Endpoints

​SCIM

​Workspaces

Creating a Management API Key

Expiration

Use Cases

Example Usage

Response Format

Organization Settings

Routes That Require a Management Key

Analytics

API Keys

BYOK

Credits

End Users

Generations

Guardrails

Observability

Organization

Private Endpoints

SCIM

Workspaces