MonsterOps logo MonsterOps
Docs / REST API / Authentication & Scopes

Authentication & Scopes

Every request to /api/v1/ is authenticated with an API key, and every endpoint requires a specific scope on that key. Keys are independent of admin login and roles — a key carries only the scopes you grant it, nothing more.

Getting a key

Issue keys in the UI at System → API Keys (superadmin or admin only):

  1. Create key → give it a name and tick the scopes it needs.
  2. The secret is shown once, at creation — it looks like mr_ followed by 48 hex characters (mr_1a2b3c…). Copy it now.
  3. Store it as a secret in whatever will call the API.

The secret is shown only once

MonsterOps stores only a hash of the key, so it can never show you the full secret again. If you lose it, revoke the key and issue a new one.

You can also create keys programmatically — but the key-management endpoints use your admin session, not an API key:

GET    /api/apikeys            # list keys (admin session)
POST   /api/apikeys            # create a key -> returns the plaintext once
DELETE /api/apikeys/{id}       # revoke a key

Authenticating a request

Send the key in the X-API-Key header:

curl -H "X-API-Key: mr_xxxxxxxxxxxxxxxx" \
     https://your-host/api/v1/sessions

For contexts where you can't set a header, the key may instead be passed as an api_key query parameter — use this sparingly, since URLs end up in logs:

curl "https://your-host/api/v1/sessions?api_key=mr_xxxxxxxxxxxxxxxx"

The CLI does the same thing under the hood — --api-key / $MONSTEROPS_API_KEY becomes the X-API-Key header.

No CSRF, no cookies

API-key requests are stateless — they aren't browser sessions, so CSRF tokens don't apply. Do not send an Authorization: Bearer header; MonsterOps authenticates the API with X-API-Key.

Scopes

A key is granted a set of scopes. Each endpoint checks for exactly one:

Scope Grants
users.read List and read users, including a user's sessions
users.write Create, update, and delete users
groups.read List and read groups and their members
groups.write Create and delete groups; add and remove members
nas.read List and read NAS devices
nas.write Create, update, and delete NAS devices
sessions.read List active sessions and a user's session history
auth_logs.read Query authentication history
coa.send Send CoA Disconnect requests

Grant the least a client needs — a monitoring tool usually only wants the *.read scopes; a signup system wants users.write.

Key lifecycle

  • Expiry — a key can be given an expires_at; after that it's rejected automatically.
  • Revoke — revoking a key in the UI disables it immediately.
  • Rotate — issue a new key, switch the client over, then revoke the old one. MonsterOps records each key's last-used time to help you spot ones that are safe to retire.

Authentication errors

Status Body (detail) Meaning
401 API key required (X-API-Key header) No key on the request
401 Invalid or revoked API key Key doesn't match, or was revoked
401 API key expired Key is past its expires_at
403 API key missing required scope: <scope> Key is valid but lacks that endpoint's scope

See Requests & Responses for the full error format.