Authentication

Overview

All requests to the MultiRoute API must be authenticated. This page describes:

How to authenticate using API keys.
How JWT-based flows may be used for configuration and key management.
Best practices for securely handling credentials.

OAuth (e.g. sign-in with Google, Apple, or GitHub) is used for dashboard access and account management; for programmatic calls to the /v1 API, use API keys.

API key authentication

The most common way to access the MultiRoute API is with an API key. API keys are opaque strings issued by MultiRoute and should be treated like passwords.

Send the key in the Authorization header:

Authorization: Bearer mrk_live_************************

Example: cURL

curl https://api.multiroute.ai/v1/chat/completions \
  -H "Authorization: Bearer $MULTIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "multiroute-chat-latest",
    "messages": [
      { "role": "user", "content": "Hello from MultiRoute!" }
    ]
  }'

Example: Node / TypeScript

const apiKey = process.env.MULTIROUTE_API_KEY!;

const response = await fetch("https://api.multiroute.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "multiroute-chat-latest",
    messages: [{ role: "user", content: "Hello from MultiRoute!" }],
  }),
});

Example: Python

import os
import requests

API_KEY = os.environ.get("MULTIROUTE_API_KEY")

resp = requests.post(
    "https://api.multiroute.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "multiroute-chat-latest",
        "messages": [{"role": "user", "content": "Hello from MultiRoute!"}],
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

JWT-based authentication

In addition to API keys, some administrative and dashboard-related endpoints (such as /v1/config and /v1/api-keys) may accept JWT access tokens issued by MultiRoute.

These tokens are generally:

Short-lived.
Tied to a specific user or service identity.
Scoped to particular actions or resources (for example, config:read, config:write, keys:manage).

You pass a JWT in the same Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The exact flows for obtaining JWTs (e.g., OAuth2 device code, web login, or service account credentials) depend on how your MultiRoute deployment is configured.

Best practices

Do not hardcode secrets: Store API keys and tokens in environment variables or a secrets manager (such as Vault, AWS Secrets Manager, or similar).
Limit scope and permissions: Use dedicated keys/tokens per service and environment (dev, staging, prod) with the minimum required privileges.
Rotate regularly: Implement a rotation strategy and automate key/token rotation where possible.
Avoid sharing keys: Do not embed API keys in mobile apps, client-side JavaScript, or other environments where they can be easily extracted.
Use HTTPS only: Always call https://api.multiroute.ai/... to protect credentials in transit.

Troubleshooting authentication

If authentication fails, you will typically see:

401 Unauthorized — The Authorization header is missing, malformed, or contains an invalid/expired credential.
403 Forbidden — The credential is valid but does not have permission to access the requested resource.

Refer to Errors & retry guidance for more details on error formats and recommended handling.