> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Management API Keys

> Manage API keys programmatically

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:

1. Go to the [Management API Keys page](https://openrouter.ai/settings/management-keys)
2. Click "Create New Key"
3. Enter a name and choose an expiration
4. 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](https://openrouter.ai/settings/management-keys) until you delete them.

<Warning>
  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.
</Warning>

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

<CodeGroup>
  ```typescript title="TypeScript SDK" expandable lines theme={null}
  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);
  ```

  ```python title="Python" expandable lines theme={null}
  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"
      }
  )
  ```

  ```typescript title="TypeScript (fetch)" expandable lines theme={null}
  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',
    },
  });
  ```
</CodeGroup>

## Response Format

API responses return JSON objects containing key information:

```json expandable lines theme={null}
{
  "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](/docs/api/api-reference/api-keys/create-a-new-api-key).

## 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](/docs/api/api-reference/analytics/get-user-activity-grouped-by-endpoint)                   |
| `GET`  | `/api/v1/analytics/meta`  | [Get available analytics metrics and dimensions](/docs/api/api-reference/analytics/get-available-analytics-metrics-and-dimensions) |
| `POST` | `/api/v1/analytics/query` | [Query analytics data](/docs/api/api-reference/analytics/query-analytics-data)                                                     |

### API Keys

| Method   | Route                 | Reference                                                                |
| -------- | --------------------- | ------------------------------------------------------------------------ |
| `GET`    | `/api/v1/keys`        | [List API keys](/docs/api/api-reference/api-keys/list-api-keys)               |
| `POST`   | `/api/v1/keys`        | [Create a new API key](/docs/api/api-reference/api-keys/create-a-new-api-key) |
| `GET`    | `/api/v1/keys/{hash}` | [Get a single API key](/docs/api/api-reference/api-keys/get-a-single-api-key) |
| `DELETE` | `/api/v1/keys/{hash}` | [Delete an API key](/docs/api/api-reference/api-keys/delete-an-api-key)       |
| `PATCH`  | `/api/v1/keys/{hash}` | [Update an API key](/docs/api/api-reference/api-keys/update-an-api-key)       |

### BYOK

| Method   | Route               | Reference                                                                                      |
| -------- | ------------------- | ---------------------------------------------------------------------------------------------- |
| `GET`    | `/api/v1/byok`      | [List BYOK provider credentials](/docs/api/api-reference/byok/list-byok-provider-credentials)       |
| `POST`   | `/api/v1/byok`      | [Create a BYOK provider credential](/docs/api/api-reference/byok/create-a-byok-provider-credential) |
| `GET`    | `/api/v1/byok/{id}` | [Get a BYOK provider credential](/docs/api/api-reference/byok/get-a-byok-provider-credential)       |
| `DELETE` | `/api/v1/byok/{id}` | [Delete a BYOK provider credential](/docs/api/api-reference/byok/delete-a-byok-provider-credential) |
| `PATCH`  | `/api/v1/byok/{id}` | [Update a BYOK provider credential](/docs/api/api-reference/byok/update-a-byok-provider-credential) |

### Credits

| Method | Route             | Reference                                                                 |
| ------ | ----------------- | ------------------------------------------------------------------------- |
| `GET`  | `/api/v1/credits` | [Get remaining credits](/docs/api/api-reference/credits/get-remaining-credits) |

### Generations

| Method | Route                         | Reference                                                                                           |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------- |
| `POST` | `/api/v1/generation/feedback` | [Submit feedback for a generation](/docs/api/api-reference/generations/submit-feedback-for-a-generation) |

### Guardrails

| Method   | Route                                                | Reference                                                                                                        |
| -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/api/v1/guardrails`                                 | [List guardrails](/docs/api/api-reference/guardrails/list-guardrails)                                                 |
| `POST`   | `/api/v1/guardrails`                                 | [Create a guardrail](/docs/api/api-reference/guardrails/create-a-guardrail)                                           |
| `GET`    | `/api/v1/guardrails/{id}`                            | [Get a guardrail](/docs/api/api-reference/guardrails/get-a-guardrail)                                                 |
| `DELETE` | `/api/v1/guardrails/{id}`                            | [Delete a guardrail](/docs/api/api-reference/guardrails/delete-a-guardrail)                                           |
| `PATCH`  | `/api/v1/guardrails/{id}`                            | [Update a guardrail](/docs/api/api-reference/guardrails/update-a-guardrail)                                           |
| `GET`    | `/api/v1/guardrails/{id}/assignments/keys`           | [List key assignments for a guardrail](/docs/api/api-reference/guardrails/list-key-assignments-for-a-guardrail)       |
| `POST`   | `/api/v1/guardrails/{id}/assignments/keys`           | [Bulk assign keys to a guardrail](/docs/api/api-reference/guardrails/bulk-assign-keys-to-a-guardrail)                 |
| `POST`   | `/api/v1/guardrails/{id}/assignments/keys/remove`    | [Bulk unassign keys from a guardrail](/docs/api/api-reference/guardrails/bulk-unassign-keys-from-a-guardrail)         |
| `GET`    | `/api/v1/guardrails/{id}/assignments/members`        | [List member assignments for a guardrail](/docs/api/api-reference/guardrails/list-member-assignments-for-a-guardrail) |
| `POST`   | `/api/v1/guardrails/{id}/assignments/members`        | [Bulk assign members to a guardrail](/docs/api/api-reference/guardrails/bulk-assign-members-to-a-guardrail)           |
| `POST`   | `/api/v1/guardrails/{id}/assignments/members/remove` | [Bulk unassign members from a guardrail](/docs/api/api-reference/guardrails/bulk-unassign-members-from-a-guardrail)   |
| `GET`    | `/api/v1/guardrails/assignments/keys`                | [List all key assignments](/docs/api/api-reference/guardrails/list-all-key-assignments)                               |
| `GET`    | `/api/v1/guardrails/assignments/members`             | [List all member assignments](/docs/api/api-reference/guardrails/list-all-member-assignments)                         |

### Observability

| Method   | Route                                     | Reference                                                                                                   |
| -------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `GET`    | `/api/v1/observability/destinations`      | [List observability destinations](/docs/api/api-reference/observability/list-observability-destinations)         |
| `POST`   | `/api/v1/observability/destinations`      | [Create an observability destination](/docs/api/api-reference/observability/create-an-observability-destination) |
| `GET`    | `/api/v1/observability/destinations/{id}` | [Get an observability destination](/docs/api/api-reference/observability/get-an-observability-destination)       |
| `DELETE` | `/api/v1/observability/destinations/{id}` | [Delete an observability destination](/docs/api/api-reference/observability/delete-an-observability-destination) |
| `PATCH`  | `/api/v1/observability/destinations/{id}` | [Update an observability destination](/docs/api/api-reference/observability/update-an-observability-destination) |

### Organization

| Method | Route                          | Reference                                                                              |
| ------ | ------------------------------ | -------------------------------------------------------------------------------------- |
| `GET`  | `/api/v1/organization/members` | [List organization members](/docs/api/api-reference/organization/list-organization-members) |

### SCIM

| Method   | Route                              | Reference                                                                                |
| -------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
| `GET`    | `/api/v1/scim/group-mappings`      | [List SCIM group mappings](/docs/api/api-reference/scim/list-scim-group-mappings)             |
| `POST`   | `/api/v1/scim/group-mappings`      | [Create a SCIM group mapping](/docs/api/api-reference/scim/create-a-scim-group-mapping)       |
| `GET`    | `/api/v1/scim/group-mappings/{id}` | [Get a SCIM group mapping](/docs/api/api-reference/scim/get-a-scim-group-mapping)             |
| `DELETE` | `/api/v1/scim/group-mappings/{id}` | [Delete a SCIM group mapping](/docs/api/api-reference/scim/delete-a-scim-group-mapping)       |
| `PATCH`  | `/api/v1/scim/group-mappings/{id}` | [Update a SCIM group mapping](/docs/api/api-reference/scim/update-a-scim-group-mapping)       |
| `GET`    | `/api/v1/scim/groups`              | [List SCIM groups](/docs/api/api-reference/scim/list-scim-groups)                             |
| `POST`   | `/api/v1/scim/sync-jobs`           | [Start a SCIM directory sync](/docs/api/api-reference/scim/start-a-scim-directory-sync)       |
| `GET`    | `/api/v1/scim/sync-jobs/{id}`      | [Get SCIM directory sync status](/docs/api/api-reference/scim/get-scim-directory-sync-status) |

### Workspaces

| Method   | Route                                                   | Reference                                                                                                  |
| -------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `GET`    | `/api/v1/workspaces`                                    | [List workspaces](/docs/api/api-reference/workspaces/list-workspaces)                                           |
| `POST`   | `/api/v1/workspaces`                                    | [Create a workspace](/docs/api/api-reference/workspaces/create-a-workspace)                                     |
| `GET`    | `/api/v1/workspaces/{id}`                               | [Get a workspace](/docs/api/api-reference/workspaces/get-a-workspace)                                           |
| `DELETE` | `/api/v1/workspaces/{id}`                               | [Delete a workspace](/docs/api/api-reference/workspaces/delete-a-workspace)                                     |
| `PATCH`  | `/api/v1/workspaces/{id}`                               | [Update a workspace](/docs/api/api-reference/workspaces/update-a-workspace)                                     |
| `GET`    | `/api/v1/workspaces/{id}/members`                       | [List workspace members](/docs/api/api-reference/workspaces/list-workspace-members)                             |
| `POST`   | `/api/v1/workspaces/{id}/members/add`                   | [Bulk add members to a workspace](/docs/api/api-reference/workspaces/bulk-add-members-to-a-workspace)           |
| `POST`   | `/api/v1/workspaces/{id}/members/remove`                | [Bulk remove members from a workspace](/docs/api/api-reference/workspaces/bulk-remove-members-from-a-workspace) |
| `GET`    | `/api/v1/workspaces/{workspace_ref}/budgets`            | [List workspace budgets](/docs/api/api-reference/workspaces/list-workspace-budgets)                             |
| `GET`    | `/api/v1/workspaces/{workspace_ref}/budgets/{interval}` | [Get a workspace budget](/docs/api/api-reference/workspaces/get-a-workspace-budget)                             |
| `PUT`    | `/api/v1/workspaces/{workspace_ref}/budgets/{interval}` | [Create or update a workspace budget](/docs/api/api-reference/workspaces/create-or-update-a-workspace-budget)   |
| `DELETE` | `/api/v1/workspaces/{workspace_ref}/budgets/{interval}` | [Delete a workspace budget](/docs/api/api-reference/workspaces/delete-a-workspace-budget)                       |