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 '{
"model": "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

Two per-minute limits apply to API requests, based on your plan:

  • Per IP address: requests from one IP address. This is checked first.
  • Per project: all requests to one project, from any IP address.
PlanPer IP / minPer project / minRequests included / month
Free304025,000
Pro100200500,000
Scale3001,0005,000,000
CustomCustomCustomCustom

So a Free project called from a single server can send up to 30 requests a minute. To reach the project limit of 40, the requests must come from more than one IP address. There are hourly limits too.

When rate limited, you'll receive a 429 response. Its limit_type field is ip or project, so you can tell which limit you hit. 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

Authentication errors return a JSON body with an error message:

Status and errorCauseSolution
401 Invalid or missing API keyNo Authorization: Bearer header, or the key is wrong, revoked or expiredSend Authorization: Bearer mr_live_..., check the key in the console, and create a new one if it was revoked or expired
403 Project is archivedThe key's project is archivedRestore the project, or use a key from an active project
429 Rate limit exceededToo many requestsWait for retry_after seconds, add backoff, or upgrade your plan

Next steps