Skip to main content
Raven supports two authentication methods: virtual keys for API access and session cookies for the dashboard. This page covers both methods and best practices for keeping your keys secure.

​
Two Authentication Methods

MethodUsed ForHow It Works
Virtual key (Bearer token)Proxy API and management APIInclude in Authorization header
Session cookieDashboard web applicationSet automatically by the browser

​
Virtual Keys

Virtual keys are the primary authentication method for the Raven API. They look like this: 
rk_live_abc123def456ghi789...

​
Key Format

PrefixEnvironmentDescription
rk_live_ProductionFor live API requests
rk_test_TestFor development and testing
Test keys (rk_test_) and live keys (rk_live_) operate on the same resources. The environment prefix is for your organizational clarity, not access isolation.

​
Using a Virtual Key

Include your virtual key in the Authorization header as a Bearer token: 
Authorization: Bearer rk_live_abc123...

​
Creating a Virtual Key

1

Navigate to Keys

Go to Keys in the dashboard sidebar.
2

Click Create Key

Enter a name, select the environment, and optionally set rate limits and expiration.
3

Copy the Key

The full key is shown only once at creation time. Copy and store it securely.
Virtual keys are hashed before storage. After creation, Raven cannot retrieve or display the full key again. If you lose a key, create a new one and revoke the old one.

​
X-Org-Id Header

For management API requests, specify which organization to operate on using the X-Org-Id header: 
Authorization: Bearer rk_live_abc123...
X-Org-Id: org_abc123
For proxy requests (/v1/chat/completions), the organization is determined automatically from the virtual key — no X-Org-Id header is needed.

​
BYOK via X-Provider-Key

Bring Your Own Key (BYOK) lets you pass your own provider API key for a specific request using the X-Provider-Key header: 
X-Provider-Key: sk-your-openai-key-here
When X-Provider-Key is present:
  • The provided key is used instead of the organization’s stored provider key
  • All gateway features still apply: logging, guardrails, rate limiting, budgets, and analytics
  • The provided key is not stored by Raven — it is used only for the current request
This is useful for:
  • Playground keys — Let users try the API with their own provider keys
  • Per-request overrides — Use a specific key for certain requests without configuring it as a provider
  • Testing — Try different provider accounts without updating org settings

​
Session Authentication

The Raven dashboard uses session-based authentication via HTTP cookies. This is handled automatically by the web application and is not used for API requests.

​
Sign-In Methods

Method
Email/password

​
Security Best Practices

Virtual keys should only be used in server-side code. Never include them in JavaScript that runs in the browser, mobile app bundles, or public repositories.
Store keys in environment variables, not in source code:
export RAVEN_API_KEY="rk_live_abc123..."
Use rk_test_ keys in development and staging environments. Reserve rk_live_ keys for production.
Configure an expiration date when creating keys. This ensures keys are rotated regularly and reduces the risk from leaked credentials.
Configure RPM and RPD limits on every key to prevent abuse. See Rate Limiting.
Review analytics regularly for unexpected usage spikes that might indicate a leaked key.
Use the key rotation feature to generate a new key and revoke the old one in a single operation.

​
Error Responses

​
Missing Authentication

{
  "error": {
    "type": "unauthorized",
    "message": "Missing or invalid API key"
  }
}
Status: 401 Unauthorized

​
Invalid Key

{
  "error": {
    "type": "unauthorized",
    "message": "Invalid API key"
  }
}
Status: 401 Unauthorized

​
Expired Key

{
  "error": {
    "type": "unauthorized",
    "message": "API key has expired"
  }
}
Status: 401 Unauthorized