Execute set up OpenRouter API authentication and configure API keys. Use when starting a new OpenRouter integration or troubleshooting auth issues. Trigger with phrases like 'openrouter setup', 'openrouter api key', 'openrouter authentication', 'configure openrouter'.
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill openrouter-install-authLoading…
Set up OpenRouter API credentials, configure the OpenAI-compatible client, verify authentication, and check credit balance. OpenRouter keys start with sk-or-v1- and authenticate against https://openrouter.ai/api/v1.
pip install openai or npm install openai)my-app-dev)sk-or-v1-... value immediately (shown only once)# .env file (add .env to .gitignore!)
OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Or export directly
export OPENROUTER_API_KEY="sk-or-v1-your-key-here"
Python:
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
default_headers={
"HTTP-Referer": "https://your-app.com", # For analytics attribution
"X-Title": "Your App Name", # Shows in dashboard
},
)
TypeScript:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY,
defaultHeaders: {
"HTTP-Referer": "https://your-app.com",
"X-Title": "Your App Name",
},
});
# Quick auth + credit check
import requests
resp = requests.get(
"https://openrouter.ai/api/v1/auth/key",
headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
)
data = resp.json()["data"]
print(f"Key: {data['label']}")
print(f"Credits used: ${data['usage']:.4f}")
print(f"Credit limit: ${data.get('limit', 'unlimited')}")
print(f"Free tier: {data['is_free_tier']}")
print(f"Rate limit: {data['rate_limit']['requests']} req / {data['rate_limit']['interval']}")
response = client.chat.completions.create(
model="google/gemma-2-9b-it:free", # Free model for testing
messages=[{"role": "user", "content": "Say hello"}],
max_tokens=50,
)
print(response.choices[0].message.content)
print(f"Tokens: {response.usage.prompt_tokens} in / {response.usage.completion_tokens} out")
| Header | Purpose | Required |
|---|---|---|
Authorization | Bearer sk-or-v1-... | Yes |
HTTP-Referer | Your app URL for dashboard attribution | Recommended |
X-Title | App name shown in OpenRouter dashboard | Recommended |
Content-Type | application/json | Yes (POST) |
| Type | Pattern | Purpose |
|---|---|---|
| Standard key | sk-or-v1-... | API access (chat completions, models) |
| Management key | sk-or-v1-... | Key provisioning only (cannot call completions) |
| BYOK provider key | Varies by provider | Bring-your-own-key for direct provider access |
A completed setup leaves you with:
OPENROUTER_API_KEY set in your environment (or a gitignored .env file), holding the sk-or-v1-... key from openrouter.ai/keyshttps://openrouter.ai/api/v1 with HTTP-Referer and X-Title headers for dashboard attribution/api/v1/auth/key: key label, credits used, credit limit, free-tier flag, and rate limitgoogle/gemma-2-9b-it:free) with its reply text and prompt/completion token countsRunning the step-4 verification against a fresh key prints something like:
Key: my-app-dev
Credits used: $0.0000
Credit limit: unlimited
Free tier: True
Rate limit: 10 req / 10s
Then the step-5 test request returns a greeting plus Tokens: 9 in / 12 out, confirming the key can call completions end-to-end. More worked examples: references/examples.md.
| HTTP | Error Code | Cause | Fix |
|---|---|---|---|
| 401 | invalid_api_key | Key malformed, revoked, or wrong | Regenerate at openrouter.ai/keys |
| 401 | missing_api_key | No Authorization header | Add Authorization: Bearer sk-or-v1-... |
| 403 | insufficient_credits | Zero balance on paid model | Add credits at openrouter.ai/credits or use :free model |
| 403 | key_disabled | Key was disabled by admin | Re-enable in dashboard or create new key |
# Programmatic key management via Management API
import requests
MGMT_KEY = os.environ["OPENROUTER_MGMT_KEY"] # Management key, not API key
# Create a new key
resp = requests.post(
"https://openrouter.ai/api/v1/keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
json={"name": "my-app-prod-v2", "limit": 100.0},
)
new_key = resp.json()["data"]["key"] # sk-or-v1-...
# List existing keys
keys = requests.get(
"https://openrouter.ai/api/v1/keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
).json()
gitleaks, trufflehog)
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).