API Key Management

Programmatically manage 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 Provisioning API Key

To use the key management API, you first need to create a Provisioning API key:

  1. Go to the Provisioning API Keys page
  2. Click “Create New Key”
  3. Complete the key creation process

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

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

Example Usage

All key management endpoints are under /api/v1/keys and require a Provisioning API key in the Authorization header.

1import requests
2
3PROVISIONING_API_KEY = "your-provisioning-key"
4BASE_URL = "https://openrouter.ai/api/v1/keys"
5
6# List all API keys
7response = requests.get(
8    BASE_URL,
9    headers={
10        "Authorization": f"Bearer {PROVISIONING_API_KEY}",
11        "Content-Type": "application/json"
12    }
13)
14
15# Create a new API key
16response = requests.post(
17    f"{BASE_URL}/",
18    headers={
19        "Authorization": f"Bearer {PROVISIONING_API_KEY}",
20        "Content-Type": "application/json"
21    },
22    json={
23        "name": "Customer Instance Key",
24        "label": "customer-123",
25        "limit": 1000  # Optional credit limit
26    }
27)
28
29# Get a specific key
30key_hash = "<YOUR_KEY_HASH>"
31response = requests.get(
32    f"{BASE_URL}/{key_hash}",
33    headers={
34        "Authorization": f"Bearer {PROVISIONING_API_KEY}",
35        "Content-Type": "application/json"
36    }
37)
38
39# Update a key
40response = requests.patch(
41    f"{BASE_URL}/{key_hash}",
42    headers={
43        "Authorization": f"Bearer {PROVISIONING_API_KEY}",
44        "Content-Type": "application/json"
45    },
46    json={
47        "name": "Updated Key Name",
48        "disabled": True  # Disable the key
49    }
50)
51
52# Delete a key
53response = requests.delete(
54    f"{BASE_URL}/{key_hash}",
55    headers={
56        "Authorization": f"Bearer {PROVISIONING_API_KEY}",
57        "Content-Type": "application/json"
58    }
59)

Response Format

API responses return JSON objects containing key information:

1{
2  "data": [
3    {
4      "created_at": "2025-02-19T20:52:27.363244+00:00",
5      "updated_at": "2025-02-19T21:24:11.708154+00:00",
6      "hash": "<YOUR_KEY_HASH>",
7      "label": "sk-or-v1-customkey",
8      "name": "Customer Key",
9      "disabled": false,
10      "limit": 10
11    }
12  ]
13}

When creating a new key, the response will include the key string itself.

Built with