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 59 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 59 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

Player data

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.

In-game

These are separate from players:read and console:write on purpose. players:read is player counts and lists such as bans and the whitelist; ingame:read is live activity, including chat. ingame:message puts text in front of every player, so a key that only watches a server never needs it. A game without these layers answers 501 capability_unsupported.

Event configuration

Command schedules

In-game events

An in-game event is a named, time-boxed, announced window over a running server that we open and close for you, and which produces a result. It is not the same thing as config_events:*, which is a scheduled settings change - "double loot this weekend" has no area and no scoreboard, so it cannot have a winner and cannot pay anybody. A game without events answers 501 capability_unsupported.

Vault

Both work on your account's Vault, so a key restricted to particular servers cannot use the routes that belong to the whole account (403 api_key_server_restricted). Saving a server also needs its owner to hold the right to change the server's settings, and loading a save the right to control the server (403 insufficient_permission otherwise). Neither scope is in the Discord bot's key preset: the bot has no Vault commands. See Your Vault.

Six splits that surprise people

Most scopes do what their name says. These six do not divide where you would expect, and each one has produced a confusing 403 for somebody - or, in the last case, spent money:

• `game_events:control` can create currency, and `game_events:write` cannot. Writing an event only describes it. Starting one that pays rewards mints coins into player wallets when it pays: they are created at that moment and taken from no other wallet. The most an event can ever pay is shown before it is started (GET .../game-events/{id}/preflight, max_this_event_can_pay) and the platform refuses to pay past it - but that ceiling is set by whoever wrote the event, so treat control as spending authority and grant it on its own key. A prize won by a player whose in-game account is not yet linked to a wallet comes back as held with a claim date - owed, not lost - and is paid on the original claim the moment that player links, so it can never be paid twice.
• `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.