Authentication#

Learn how WatchLLM authenticates API requests and how to manage your API keys.

Overview#

WatchLLM uses Bearer token authentication with project-scoped API keys. Every request to the proxy must include a valid API key in the Authorization header.

API Key Format#

WatchLLM API keys follow a specific format for easy identification:

Making Authenticated Requests#

HTTP Header#

Include your API key as a Bearer token:

POST https://proxy.watchllm.dev/v1/chat/completions
Authorization: Bearer lgw_proj_your_key_here
Content-Type: application/json
 
{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello!"}]
}

Using OpenAI SDK#

The standard OpenAI SDK handles authentication automatically:

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: 'lgw_proj_your_key_here',
  baseURL: 'https://proxy.watchllm.dev/v1',
});

from openai import OpenAI
 
client = OpenAI(
    api_key="lgw_proj_your_key_here",
    base_url="https://proxy.watchllm.dev/v1",
)

Using cURL#

curl https://proxy.watchllm.dev/v1/chat/completions \
  -H "Authorization: Bearer lgw_proj_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Authentication Flow#

When a request arrives at the WatchLLM proxy:

1. Key Extraction — The Authorization: Bearer <key> header is parsed
2. Format Validation — The key must match the lgw_proj_ or lgw_test_ prefix pattern
3. Database Lookup — The key is validated against the api_keys table in Supabase
4. Project Resolution — The associated project record is fetched (plan, settings, cache config)
5. Rate Limit Check — Per-key and per-IP rate limits are enforced
6. Request Processing — The request proceeds to cache lookup and/or provider forwarding

Error Responses#

Managing API Keys#

Creating Keys#

1. Log in to the WatchLLM Dashboard
2. Navigate to your project
3. Go to Settings → API Keys
4. Click Generate New Key
5. Copy and securely store the key — it won't be shown again

Rotating Keys#

To rotate a key without downtime:

1. Generate a new key in the dashboard
2. Update your application to use the new key
3. Verify the new key works in production
4. Deactivate the old key

Deactivating Keys#

Deactivated keys immediately stop working. Any requests using a deactivated key will receive a 401 response.

Security Best Practices#

Do's#

• Store keys in environment variables — never hardcode in source code
• Use separate keys for development, staging, and production
• Rotate keys regularly — at least every 90 days
• Monitor key usage in the dashboard for anomalies
• Use server-side only — never expose keys in client-side JavaScript

Don'ts#

• Don't commit keys to Git — add .env to .gitignore
• Don't share keys between team members — create individual keys
• Don't log keys — ensure your logging doesn't capture authorization headers
• Don't use project keys for testing — use test keys (lgw_test_) instead

Environment Variable Setup#

Node.js#

# .env
WATCHLLM_API_KEY=lgw_proj_your_key_here

const client = new OpenAI({
  apiKey: process.env.WATCHLLM_API_KEY,
  baseURL: 'https://proxy.watchllm.dev/v1',
});

Python#

# .env
WATCHLLM_API_KEY=lgw_proj_your_key_here

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["WATCHLLM_API_KEY"],
    base_url="https://proxy.watchllm.dev/v1",
)

BYOK Authentication#

When using Bring Your Own Key (BYOK) mode, authentication works in two layers:

1. WatchLLM Authentication — Your lgw_proj_ key authenticates with WatchLLM
2. Provider Authentication — Your stored provider keys (OpenAI, Anthropic, Groq) are used to authenticate with upstream providers

See the BYOK Guide for detailed setup instructions.