Authentication

ModelRelay has three kinds of credentials:

Secret API keys

Secret keys belong to a project and have full access to it. Signing up creates a default project and its first key. Create more on the project’s API Keys page in the dashboard, or with mrl (see Getting started).

How you send the key depends on the endpoint:

The native API rejects a secret key sent as Authorization: Bearer with 401, so that header stays reserved for bearer tokens. On the /v1 endpoints, ModelRelay accepts the headers the OpenAI and Anthropic SDKs send.

Keep secret keys on your server. Never put them in client-side code, mobile apps, or public repositories.

Spend-limited keys

A key can carry a hard lifetime spend limit, for example when you hand a key to someone else:

mrl keys create --name app-review --spend-limit 500 --print   # $5.00

Once the key’s settled spend reaches the limit, billable endpoints refuse it with 402 API_KEY_SPEND_LIMIT_REACHED. The limit cannot be raised; revoke the key and create another. A spend-limited key cannot mint customer tokens.

Zero data retention

A key created with require_zdr (mrl keys create --require-zdr, or the checkbox on the dashboard’s key form) is served only by routes whose provider keeps no request content, and is refused for features that would have ModelRelay store content, such as response_cache and state_id. A model with no such route fails with 400 rather than falling back. The setting cannot be changed after creation, and such a key cannot mint customer tokens. To apply the same restriction to every key and customer token in the account, turn on require_zdr for the account instead. See Zero Data Retention.

Customer bearer tokens

Customer tokens are short-lived bearer tokens scoped to one of your customers. Requests made with one are metered to that customer and limited by their tier. Use them when an end user’s browser or app calls ModelRelay directly.

Your backend mints a token with a secret key. The customer must already exist in the project:

curl https://api.modelrelay.ai/api/v1/auth/customer-token \
  -H "X-ModelRelay-Api-Key: $MODELRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_external_id": "user_42"}'

The response includes token and expires_at. Send token to the client, which uses it as a bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Project scope comes from the secret key. Requests that include project_id are rejected. See Customer tokens for TTLs, tiers, and creating customers.

Account tokens

Creating API keys and tiers uses your account login rather than an API key. mrl auth login stores an account token in the active profile:

mrl auth login --web                      # browser OAuth; add --provider google for Google
mrl auth login --device                   # approve a link from any device
mrl auth logout                           # clear the stored token

Device sign-in uses the OAuth 2.0 Device Authorization Grant; see Device sign-in.

Security practices

1. Load keys from environment variables or a secret manager; never hardcode them.
2. Use customer tokens for anything that runs on a user’s device.
3. Rotate keys by creating a new key, deploying it, then revoking the old one with mrl keys revoke <key-id> or in the dashboard.
4. Use spend-limited keys for keys you hand to others.
5. Watch usage in the dashboard for unusual patterns.