Authentication

Two credential types

Credential	For	How it is sent
Session	The panel UI and browser flows	Session cookie
API key	Scripts, bots, integrations	Authorization: Bearer <key> header

Use API keys for anything programmatic — do not automate logins or scrape session cookies. Authorization: Bearer is the only header the panel authenticates an API key from; a request without it falls back to session-cookie auth.

Create an API key in the panel

You need apikey.read to see the page and apikey.write to create a key (admin.read covers reading, admin.write covers both). Non-admins see and manage only their own keys.

1. Sign in and open Admin → Access Control → API Keys.
2. Select Create API Key.
3. Fill in the dialog:
   • Name * — a descriptive label, for example Billing System Integration.
   • Permissions — leave All my permissions on to inherit everything your account can do, or switch it off and tick individual scopes. You cannot grant a scope you do not hold yourself.
   • Expiration — 90 days (recommended) by default; also 7 days, 30 days, 180 days, 1 year, or Never expires.
   • Rate Limit — requests per minute for this key. The default is 100; see rate limits.
4. Select Create API key.
5. Copy the key from Your API Key into a secret manager. It is shown once — later you can only revoke and recreate it.

Every key starts with catalyst_:

curl -H "Authorization: Bearer $CATALYST_API_KEY" \
  https://panel.example.com/api/servers

Manage keys in the panel

• The list shows each key’s status (active, disabled, expired), permissions, rate limit, request count, and last use.
• Edit key changes the name, the enabled state, and the rate limit. Permissions and expiry are fixed at creation — revoke the key and create a new one to change them.
• Revoke key deletes the key immediately; requests using it fail with 401. Revoking an agent (node) key disconnects that node’s agent, so the panel asks you to confirm by typing the node ID first.

Expiry and live permission checks

• An expired or disabled key is rejected with 401 before the request reaches the route.
• A key never outlives its owner’s permissions. On every request the panel re-resolves the owner’s current role permissions and rejects a key whose scopes are no longer held (403). A key created with All my permissions tracks the owner’s current permissions, so a demoted owner shrinks (or zeroes) the key automatically.

Automate key management

The panel’s own endpoints work from a script. Mutating calls need apikey.write; the list and usage reads need apikey.read.

BASE=https://panel.example.com
AUTH="Authorization: Bearer $CATALYST_API_KEY"

# Create a key. expiresIn is seconds (3600–31536000); omit it for no expiry.
curl -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name":"billing-sync","permissions":["server.read","backup.read"],
       "expiresIn":7776000,"rateLimitMax":100,"rateLimitTimeWindow":60000}' \
  "$BASE/api/admin/api-keys"

# The response data.key is the full secret — store it now, it is never returned again.

# List keys, inspect usage, then revoke.
curl -H "$AUTH" "$BASE/api/admin/api-keys"
curl -H "$AUTH" "$BASE/api/admin/api-keys/<keyId>/usage"
curl -X DELETE -H "$AUTH" "$BASE/api/admin/api-keys/<keyId>"

Create the replacement key first, deploy it, then delete the old one — never delete-then-create.

Node credentials

Nodes authenticate with their own node ID + agent API key over the agent channel (/ws?nodeId=<id>), managed through registering a node. Node credentials are never valid for the user-facing API, and user API keys are never valid for the agent channel.

Related

Authorization & permissions · Errors