Sign in with a local user account or static access key

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:

Cause	Fix
Missing `Authorization` header	Add `Authorization: Bearer <token>` to your request
Expired JWT token	Log in again at `/api/auth/login` to get a new token
Wrong access key	Check `server.access_key` in your `config.yml`
Access key auth disabled	Set `access_key_enabled: true` or use a user account
Inactive account	Contact 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.

Get Started

Configuration

Admin Dashboard

Authentication

Sign in with a local user account or static access key

Access key authentication

User account authentication

Register an account

Log in

Use the token in API requests

Troubleshooting

401 Unauthorized

​Access key authentication

​User account authentication

​Register an account

​Log in

​Use the token in API requests

​Troubleshooting

​401 Unauthorized

Access key authentication

User account authentication

Register an account

Log in

Use the token in API requests

Troubleshooting

401 Unauthorized