---

name: openrouter-install-auth description: 'Set up OpenRouter API authentication and configure API keys. Use when starting a new OpenRouter integration, rotating keys, or troubleshooting auth issues. Triggers: ''openrouter setup'', ''openrouter api key'', ''configure openrouter auth'', ''sk-or key''.

' allowed-tools: Read, Write, Edit, Grep, Bash(python3:), Bash(node:), Bash(pip:), Bash(npm:) version: 1.20.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• openrouter
• api
• authentication
• setup compatibility: Designed for Claude Code

---

OpenRouter Install & Auth

Overview

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.

Prerequisites

• OpenRouter account (free at openrouter.ai)
• Python 3.8+ or Node.js 18+
• OpenAI SDK (pip install openai or npm install openai)

Instructions

1. Generate an API Key

1. Go to openrouter.ai/keys
2. Click Create Key, name it (e.g., my-app-dev)
3. Copy the sk-or-v1-... value immediately (shown only once)
4. Optionally set a credit limit on the key for spend control

2. Configure Environment

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

3. Initialize the Client

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",
  },
});

4. Verify Authentication

# 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']}")

5. Send a Test Request

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")

Required Headers

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)

Key Formats

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

Output

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/keys
• A configured OpenAI-SDK client pointed at https://openrouter.ai/api/v1 with HTTP-Referer and X-Title headers for dashboard attribution
• An auth-verification printout from /api/v1/auth/key: key label, credits used, credit limit, free-tier flag, and rate limit
• A test completion from the free model (google/gemma-2-9b-it:free) with its reply text and prompt/completion token counts

Examples

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

Error Handling

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

Key Rotation

# 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()

Enterprise Considerations

• Store keys in a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault)
• Use management keys to provision per-service API keys programmatically
• Set credit limits per key to isolate blast radius
• Rotate keys on a schedule (90 days recommended)
• Add secret scanning to CI pipelines (e.g., gitleaks, trufflehog)
• Use BYOK for direct provider billing when volume justifies it

References

• Examples | Errors
• OpenRouter Quickstart | Auth Docs | Key Provisioning