Authentication & Virtual Keys

Routic uses API Keys for authentication, following the same format and usage as OpenAI.

How authentication works

Include your API Key in the Authorization header on every request:

Authorization: Bearer sk-xxxxxxxx

Never put your API Key in URL parameters. All requests must use HTTPS.

Get an API Key

Log in to the Routic dashboard
Go to the "API Keys" page
Click "Create new key"
Copy the key and store it securely

The key is only shown once after creation. If you lose it, you'll need to revoke the old key and create a new one.

API Key format

Prefix: sk-
Length: 48 characters
Example: sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Routic keys use the sk- prefix, different from OpenAI's sk-proj-. The two are not interchangeable — a Routic key only works with the Routic Base URL:

# ✅ Correct — specify both base_url and api_key
client = OpenAI(
    base_url="https://api.routic.ai/v1",
    api_key="sk-xxxxxxxx",   # Routic key
)

# ❌ Wrong — key without base_url → request goes to OpenAI
client = OpenAI(api_key="sk-xxxxxxxx")

# ❌ Wrong — OpenAI key with Routic base URL
client = OpenAI(
    base_url="https://api.routic.ai/v1",
    api_key="sk-proj-xxxxxxxx",  # This is an OpenAI key
)

Key security

⚠️ Never do this

Commit API Keys to Git (including .env files)
Hard-code API Keys in frontend code (React, Vue, etc.)
Embed API Keys in client-side applications
Share API Keys in public issues, forums, or chats

✅ Recommended practices

Store keys in environment variables: export ROUTIC_API_KEY="sk-xxxxxxxx"
Use .env files and ensure .gitignore includes .env
Proxy through your backend — the frontend calls your server, which calls Routic
Use separate keys for different environments (dev/staging/production)

If your key is leaked

Revoke the leaked key immediately in your dashboard
Create a new key
Update all services that used the old key
Check usage logs for any unauthorized calls

Key management

Action	Description
Create	Each user can create multiple keys for different use cases
Revoke	Takes effect immediately. In-flight requests are unaffected; new requests are rejected
Name	Give keys meaningful names (e.g., `prod-backend`, `dev-testing`)

All keys under the same account share the account balance.

Multi-key strategies

Scenario	Strategy
Frontend + backend	Backend uses one key; frontend never calls the API directly
Multiple services	One key per service — easier to track usage
Dev vs production	Use a separate account for dev to avoid accidental impact on production
Rate limiting	When one key hits its limit, rotate to another (each key has independent limits)

Authentication errors

Error code	HTTP status	Meaning	Solution
`invalid_api_key`	401	Key is malformed or doesn't exist	Check that the key was copied completely
`expired_api_key`	401	Key has expired or been revoked	Create a new key in the dashboard
`missing_api_key`	401	No Authorization header provided	Add `Authorization: Bearer sk-xxx`