Authenticate API requests with access keys and JWT tokens

Every request to a protected MonoRelay endpoint must include a valid credential. MonoRelay supports two authentication methods: a static access key configured in config.yml, and a short-lived JWT token obtained by logging in through the auth API. Both methods use the same Authorization: Bearer header pattern, making them compatible with standard OpenAI SDKs without any special client configuration.

Authentication methods

Method 1: Access key

When server.access_key_enabled is true in your config.yml, you can authenticate by passing the configured access_key value directly. The key can be sent in either of two headers:

string

Bearer token header. Pass Bearer <your-access-key> as the value.

string

Alternative header for clients that cannot set a custom Authorization value. Pass the raw key with no Bearer prefix.

The access key is set in config.yml:

config.yml

server:
  access_key: "prisma-relay-change-me"
  access_key_enabled: true

Example using curl with the Authorization header:

curl https://relay.example.com/v1/chat/completions \
  -H "Authorization: Bearer prisma-relay-change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Example using the X-Access-Key header:

curl https://relay.example.com/v1/chat/completions \
  -H "X-Access-Key: prisma-relay-change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Method 2: JWT token

User accounts created through POST /api/auth/register can obtain a JWT token by logging in. Pass the token as a Bearer credential on subsequent requests. Tokens are short-lived; use the refresh token to obtain a new access token without re-authenticating.

string

required

Bearer <jwt-token> where the token is the access_token value returned by POST /api/auth/login.

Step 1 — Log in to obtain a token:

curl https://relay.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "correct-horse-battery-staple"
  }'

The response includes an access_token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Step 2 — Use the token to call an API endpoint:

curl https://relay.example.com/v1/chat/completions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Public endpoints

The following endpoints do not require authentication and can be called without any credentials:

Endpoint	Description
`GET /health`	Server health check and provider status
`GET /v1/models`	List available models
`GET /api/info`	Server connection info and base URL
`POST /api/auth/login`	Obtain a JWT token
`POST /api/auth/register`	Create a new user account

Python SDK example

Because MonoRelay is OpenAI-compatible, you can use the official openai Python library by pointing it at your MonoRelay instance. Pass your access key or JWT token as the api_key argument.

from openai import OpenAI

client = OpenAI(
    base_url="https://relay.example.com/v1",
    api_key="prisma-relay-change-me",   # access key or JWT token
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)

To use a JWT token instead, replace the api_key value with the access_token string returned by POST /api/auth/login.

Error responses

Status	Body	Cause
`401`	`{"error": {"message": "Unauthorized", "type": "auth_error"}}`	Missing credential, invalid access key, or expired/malformed JWT token

If both access_key_enabled is false and no valid JWT is present, all protected endpoints return 401 Unauthorized. Ensure at least one authentication method is configured before making API calls.

Overview

OpenAI-Compatible

Anthropic-Compatible

Management API

Authenticate API requests with access keys and JWT tokens

Authentication methods

Method 1: Access key

Method 2: JWT token

Public endpoints

Python SDK example

Error responses

​Authentication methods

​Method 1: Access key

​Method 2: JWT token

​Public endpoints

​Python SDK example

​Error responses

Authentication methods

Method 1: Access key

Method 2: JWT token

Public endpoints

Python SDK example

Error responses