Docs

Documentation

Secure API authentication

Authenticate with project API keys. Manage production and test keys, implement rotation, and follow security best practices.

All ModelRiver API requests require authentication using project API keys. Keys are scoped to a specific project and determine which workflows, providers, and data you can access.

API key format

All API keys use the mr_live_ prefix. When creating a key you choose an expiration (1 day, 7 days, 30 days, 60 days, 90 days, or Never). Use short-lived keys for development and longer durations for production.

Using API keys

Header authentication

Include your API key in the Authorization header:

Bash
curl -X POST https://api.modelriver.com/v1/ai \
-H "Authorization: Bearer mr_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow": "my-workflow",
"messages": [{"role": "user", "content": "Hello"}]
}'

With OpenAI SDK

PYTHON
1from openai import OpenAI
2 
3client = OpenAI(
4 base_url="https://api.modelriver.com/v1",
5 api_key="mr_live_YOUR_API_KEY"
6)
JAVASCRIPT
1import OpenAI from "openai";
2 
3const client = new OpenAI({
4 baseURL: "https://api.modelriver.com/v1",
5 apiKey: "mr_live_YOUR_API_KEY",
6});

Managing API keys

Creating keys

  1. Navigate to your project in the ModelRiver console
  2. Go to Settings → API Keys
  3. Click Create API Key
  4. Choose an expiration period
  5. Copy and store the key securely: it won't be shown again

Revoking keys

  1. Go to Settings → API Keys
  2. Find the key to revoke
  3. Click Revoke
  4. The key is immediately invalidated

Warning: Revoking a key immediately breaks all applications using it. Ensure you've updated all deployments before revoking.

Key rotation

For security, rotate your API keys periodically:

  1. Create a new key in the console
  2. Update your deployments to use the new key
  3. Verify all services are working with the new key
  4. Revoke the old key once all services are migrated

Environment variable approach

Store keys in environment variables, never in source code:

Bash
# .env (never commit this file)
MODELRIVER_API_KEY=mr_live_YOUR_API_KEY
PYTHON
1import os
2from openai import OpenAI
3 
4client = OpenAI(
5 base_url="https://api.modelriver.com/v1",
6 api_key=os.environ["MODELRIVER_API_KEY"]
7)
JAVASCRIPT
1const client = new OpenAI({
2 baseURL: "https://api.modelriver.com/v1",
3 apiKey: process.env.MODELRIVER_API_KEY,
4});

Rate limiting

API keys are subject to rate limits based on your plan:

PlanRequests/minRequests/month
Free6025,000
Starter120100,000
Core300500,000
Growth6002,000,000

When rate limited, you'll receive a 429 response. See Error handling for retry strategies.

Security best practices

  1. Never expose keys in client-side code: Always proxy API calls through your backend
  2. Use environment variables: Store keys in .env files or secret management services
  3. Add .env to .gitignore: Prevent accidental commits of API keys
  4. Use separate keys per environment: Production, staging, and development should each have their own keys
  5. Rotate keys regularly: At minimum quarterly, or immediately if compromised
  6. Monitor key usage: Check Request Logs for unusual activity
  7. Use short-lived keys for development: Choose 1-day or 7-day expiration so forgotten keys auto-expire
  8. Restrict network access: Use IP allowlisting where possible

Backend proxy pattern

Never call ModelRiver directly from the browser. Instead, proxy through your backend:

JAVASCRIPT
1// ❌ DON'T: Client-side (exposes key)
2const client = new OpenAI({
3 baseURL: "https://api.modelriver.com/v1",
4 apiKey: "mr_live_EXPOSED_KEY", // Visible in browser dev tools!
5 dangerouslyAllowBrowser: true,
6});
7 
8// ✅ DO: Server-side proxy
9// api/chat.js (your backend)
10export async function POST(req) {
11 const { messages } = await req.json();
12
13 const response = await fetch("https://api.modelriver.com/v1/chat/completions", {
14 method: "POST",
15 headers: {
16 "Authorization": `Bearer ${process.env.MODELRIVER_API_KEY}`,
17 "Content-Type": "application/json",
18 },
19 body: JSON.stringify({ model: "my_workflow", messages }),
20 });
21 
22 return response;
23}

Troubleshooting authentication

ErrorCauseSolution
401 authentication_errorInvalid or expired keyVerify key in console, create new if needed
401 missing_api_keyNo Authorization headerAdd Bearer mr_live_... header
403 forbiddenKey doesn't have accessCheck key belongs to the correct project
429 rate_limit_exceededToo many requestsImplement backoff or upgrade plan

Next steps