Skip to content
CatalystCatalyst Docs

Authorization & Permissions

The model

Section titled “The model”
  • Users get powers through roles. A request is allowed when the caller’s effective permission set satisfies the permission the route requires. Roles may also carry server-scoped and node-scoped grants, merged in for the specific server being touched.
  • API keys carry their own scopes, chosen at creation, and can never exceed their owner’s permissions — see Expiry and live permission checks.
  • Subusers are granted a subset of the server-scoped list by the server owner.

Admin bits

Section titled “Admin bits”
Value Grants
* Everything (Super Admin).
admin.write Every concrete permission, read or write.
admin.read Every read permission: anything ending in .read, plus node.view_stats, backup.download, and diagnostics.download.

A resource-scoped admin bit (admin.read:<id>) does not widen to all resources.

Permission catalog

Section titled “Permission catalog”

These are the exact strings the API key and role editors offer. Fetch them live from GET /api/admin/api-keys/permissions-catalog.

Category Permissions
Administration *, admin.read, admin.write
Servers server.read, server.create, server.start, server.stop, server.delete, server.suspend, server.transfer, server.schedule, server.update, server.install, server.reinstall, server.rebuild, server.clone, server.kill, server.network, server.storage, server.archive, server.migrate
Nodes node.read, node.create, node.update, node.delete, node.view_stats, node.manage_allocation, node.assign, node.server_manage, node.agent_control
Locations location.read, location.create, location.update, location.delete
Templates template.read, template.create, template.update, template.delete
Users user.read, user.create, user.update, user.delete, user.ban, user.unban, user.set_roles
Roles role.read, role.create, role.update, role.delete
Backups backup.read, backup.create, backup.delete, backup.restore, backup.download, backup.pin
Files file.read, file.write
Console console.read, console.write
Databases database.read, database.create, database.delete, database.rotate
Alerts alert.read, alert.create, alert.update, alert.delete
API Keys apikey.manage, apikey.read, apikey.write
Server Content mods.manage, plugins.manage
Panel Operations migration.manage, update.trigger, diagnostics.download

GET /api/roles/permissions-catalog appends a Plugins category for tokens that enabled plugins declare in their manifest’s userPermissions; those tokens only exist while the plugin is installed and enabled. The API-key catalog returns only the built-in categories above.

Server-scoped permissions

Section titled “Server-scoped permissions”

The grantable set for one server — subuser grants and the role wizard’s scoped-access step — is GET /api/permissions/server:

server.read, server.start, server.stop, server.kill, server.install, server.reinstall, server.rebuild, server.update, server.network, server.storage, server.archive, server.migrate, server.transfer, server.delete, server.schedule, server.clone, console.read, console.write, file.read, file.write, backup.read, backup.create, backup.restore, backup.delete, backup.download, backup.pin, database.read, database.create, database.rotate, database.delete, alert.read, alert.create, alert.update, alert.delete, mods.manage, plugins.manage.

Server owners and full admins implicitly hold the whole set for their servers.

When you get a 403

Section titled “When you get a 403”

PERMISSION_DENIED means authentication worked but the identity lacks the permission — not that the endpoint is wrong:

  1. Check which identity you sent (session user vs. which API key).
  2. Compare its permissions against the endpoint’s requirement in the API reference.
  3. Ask an administrator to widen the role or scope, or use a better-scoped key. A key is also rejected when its owner no longer holds a scope the key was granted.

Request the smallest scope that works today and widen later. Permission names are stable identifiers: cache the catalog, but re-fetch it after a panel upgrade if you start seeing unknown permissions.

Section titled “Related”