MonsterOps logo MonsterOps
Docs / System / API Keys

API Keys

Overview

API Keys issue scoped credentials for external systems and scripts to use the MonsterOps REST API (and the monsterops CLI against a remote instance). Keys are independent of admin roles and carry their own scopes (e.g. users.read, nas.write), so you can grant exactly the access an integration needs — no more.

Where things are

  • Key list — issued keys with their scopes and status.
  • Create key — name it and select scopes. The secret is shown once at creation — copy it then.
  • Revoke — disable a key immediately.

Using a key

Programmatic clients send the key in the X-API-Key header and are not subject to CSRF (that only applies to cookie-based browser sessions):

curl -H "X-API-Key: <API_KEY>" https://your-host/api/v1/users

# the CLI against a remote instance:
monsterops --url https://your-host --api-key <API_KEY> users list --format json

The REST API lives at /api/v1/ with a versioned OpenAPI spec (enable /api/docs with MONSTEROPS_DEBUG=true in non-production). For the full endpoint reference, see the REST API section.

Common tasks

  • Give a monitoring tool read-only access — create a key with only *.read scopes.
  • Automate provisioning — a key with users.write for a signup system.
  • Rotate a key — create a new one, switch the client, then revoke the old.

Problems you may hit

You didn't copy the secret

A key's secret is shown only at creation. If you lost it, revoke the key and issue a new one — it can't be retrieved later.

  • 403 Forbidden from the API — the key lacks the scope for that endpoint; add the scope or use a key that has it.
  • 401 Unauthorized — the key is revoked, expired, or the header is wrong (it must be X-API-Key: <key>, not Authorization: Bearer).
  • REST API — the full endpoint reference these keys unlock
  • CLI — uses an API key against a running instance
  • Roles — admin roles vs. API scopes
  • Configuration — MONSTEROPS_DEBUG for /api/docs