API Scopes and Permissions

How scopes work

Every API key carries a list of scopes. A scope is permission to call a particular kind of endpoint, and the key can call nothing it was not granted. You choose the list when you create the key in the panel, and it cannot be widened afterwards - to change what a key can do, create a new one.

Three rules decide everything else:

• There is no hierarchy. files:write does not imply files:read. backups:write does not imply backups:create or backups:restore. If a key needs to both read and write something, grant both scopes.
• There is no wildcard. There is no * scope and no "all access" option. Selecting everything in the panel writes all 44 scope names out explicitly, so what a key can do is always visible in its own record.
• Scopes are matched exactly, and they are case-sensitive. Servers:Read is not servers:read.

A scope on its own is not enough. The key also has an owner, and the owner must still hold the underlying account permission. If someone loses a role, every key they created stops being able to do the thing that role allowed, within about a minute - even though the scope is still written on the key. The two failures look different on purpose:

You never have to guess what a key holds. GET /account/keys/current returns the calling key's own scopes and needs no scope of its own, so even a key with a mistyped scope list can still ask what it can do.

The 44 scopes

This is the complete vocabulary. GET /api/public/v1/meta/scopes returns the same list as JSON and needs no API key, so a client can always check it against a live server.

Account, billing and keys

Servers and lifecycle

Console, logs and files

Settings, players, backups and mods

Webhooks, bundles, tickets and Windrose Plus

Economy and scheduled events

Live map

The live map is read-only over the API, so there is no map write scope. One that appeared in this list and granted nothing would be worse than an absent one — you would tick it, expect to act on the map, and get nothing back. It goes in when the write routes do.

There is no scope for resetting a region, and there will not be one. Resetting destroys everything players built in a 512 x 512 block area. It stays in the panel, where it is gated on a backup that has to finish first, an owner-only permission, and a dialog naming who has a land claim there. None of that survives being reduced to a key in a script.

Read `map/capabilities` before calling anything else. Games differ: 7 Days to Die has regions, land claims and cell actions; Valheim has fog, history and a leaderboard. The flag set is the same everywhere and only the values change, so a flag that is false is a layer the game does not have, not one we have not built.

Event configuration

Command schedules

Five splits that surprise people

Most scopes do what their name says. These five do not divide where you would expect, and each one has produced a confusing 403 for somebody:

• `webhooks:write` cannot update, test or redeliver a webhook. It covers create and delete only; PATCH, POST /test and POST /redeliver all need webhooks:manage. A key that manages webhooks wants all three of webhooks:read, webhooks:write and webhooks:manage.
• `servers:read` and `players:read` split the player endpoints between them. Reading the current player count (GET /servers/{id}/players) and the list catalogue under /players/lists are servers:read. Reading a specific list's contents (GET /servers/{id}/players/lists/{listKey}) and the discovery route GET /servers/{id}/player-lists are players:read. Anything that inspects player lists should hold both.
• `servers:write` does not cover player-list writes. Adding or removing a ban, whitelist or op entry needs players:write.
• `metrics:read` does not cover changing resource limits. Reading them is metrics:read; the PUT is servers:write.
• `console:read` does not cover clearing history. Clearing is a write - it needs console:write.

Scopes that do not exist

If you went looking for one of these, here is what to use instead.

Choosing scopes for a key

Grant the smallest set that lets the job finish, and give each job its own key. A key that only reads status cannot be turned into one that wipes a server, and when something goes wrong you can revoke one integration without breaking the rest.

Two scopes deserve their own key with nothing else on it: maintenance:execute, which can wipe and reinstall, and backups:restore, which overwrites live data. windrose:admin belongs in the same category, because it can read an RCON password in clear text.

If you are unsure what a running integration actually uses, call GET /account/keys/current with its key and compare the scopes it holds against what it needs. GET /account/audit shows what it has been calling for the last 24 hours, including calls that were rejected.