Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Excurs1ons/MonoRelay/llms.txt

Use this file to discover all available pages before exploring further.

MonoRelay supports two local authentication methods: a simple static access key for single-user or server-to-server deployments, and full user accounts with username and password that each receive a short-lived JWT token.

​
Access key authentication

The access key is the simplest way to authenticate. Set a key in config.yml under server.access_key, then pass it in every request as either a Bearer token or an X-Access-Key header. No registration or login step is required. 
server:
  access_key: "your-secret-access-key"
  access_key_enabled: true

# Using Authorization header
curl https://your-domain/v1/chat/completions \
  -H "Authorization: Bearer your-secret-access-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

# Using X-Access-Key header
curl https://your-domain/v1/chat/completions \
  -H "X-Access-Key: your-secret-access-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
Access key auth is best for automated scripts and internal tooling where you control both ends of the connection. For shared deployments with multiple people, use user accounts instead.
To disable access key authentication entirely and require user accounts, set access_key_enabled: false in config.yml: 
server:
  access_key_enabled: false

​
User account authentication

User accounts let multiple people access a MonoRelay instance with individual credentials. Each user logs in and receives a JWT token that they include in API requests.

​
Register an account

Send a POST request to /api/auth/register with a username, email address, and password. The password must be at least 8 characters. 
curl -X POST https://your-domain/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "email": "alice@example.com",
    "password": "securepassword123"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "username": "alice",
    "email": "alice@example.com",
    "is_admin": true
  }
}
The first user to register automatically becomes a super admin with full administrative privileges.

​
Log in

Send a POST request to /api/auth/login with your username and password. 
curl -X POST https://your-domain/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "securepassword123"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "username": "alice",
    "email": "alice@example.com",
    "is_admin": true
  }
}
The access_token in the response is a JWT that expires after 24 hours (expires_in is in seconds).

​
Use the token in API requests

Include the token in the Authorization header as a Bearer token on every subsequent request. 
curl https://your-domain/v1/chat/completions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

​
Troubleshooting

​
401 Unauthorized

A 401 Unauthorized response means the request either had no credentials or the credentials were rejected. Common causes:
CauseFix
Missing Authorization headerAdd Authorization: Bearer <token> to your request
Expired JWT tokenLog in again at /api/auth/login to get a new token
Wrong access keyCheck server.access_key in your config.yml
Access key auth disabledSet access_key_enabled: true or use a user account
Inactive accountContact your MonoRelay administrator
Tokens expire after 24 hours. Store your credentials securely and re-authenticate when you receive a 401 on a previously working token.

Build docs developers (and LLMs) love

Get started for freeTalk to us