Tokens and permissions

Anyone may read what you open to visitors. Everything else takes a token or a panel account, and each one can do only what its permissions say.

Make a token in game

1. Run /worldapi token create <name>. A chest menu opens.
2. Click the groups you want.
3. Pick a lifetime: never, 1, 7, 30, or 90 days.
4. Press “Create token”. The token shows up once in your chat as “[Click to copy]”.

Clients send it as Authorization: Bearer <token>. The admin panel's Tokens page makes tokens too.

Commands

Every command needs worldapi.admin, which operators have.

Command	What it does
/worldapi	Opens a menu with all of the below: state, panel code, tokens, accounts, groups, reload
/worldapi admin [group]	A code for the admin panel: your first account, or a new password for yours
/worldapi token create <name>	Opens the token menu
/worldapi token list	Every token with its permissions and expiry
/worldapi token revoke <name>	Stops a token at once
/worldapi reload	Applies config.yml without a restart
/worldapi status	Shows what's running

Groups

A token or an account lists permissions and groups. Four groups come ready; change them or add your own in auth.groups.

Group	Gets
viewer	Everything a site or a curious agent reads: the server, worlds, players with their places and inventories, events, chat
moderator	viewer, plus the console log, the command catalog, player changes, kicks, bans, and the whitelist; it sees operators but can't make them
admin	Everything but writing files and Java scripts
owner	Everything

Permissions

Permission	Grants
server:read	The server, worlds, blocks, entities, plugins, and performance
players:read	Players, statistics, advancements, sessions, and leaderboards
players:private	Coordinates, inventories, ender chests, containers, and death places
events:read	The event history and the live feed
chat:read	Chat in the history and the live feed
logs:read	The console, players' commands, and files under logs/
system:read	The host: memory, swap, disk, CPU, and container limits
world:write	Time, weather, rules, the border, blocks, containers, entities, explosions, lightning, sounds, particles
players:write	Teleports, messages, player state, inventories, effects, advancements
players:moderate	Kicks, bans, the whitelist, the operator list, vanished players, and IP addresses
server:console	Console commands, the command catalog, and making operators; it reaches as far as owner
commands:read	The command catalog: every command with its plugin, description, and usage, without running any
server:control	Saving, restarting, stopping, and world seeds
files:read	Server and plugin configs
files:write	Changing them. Only owner has it unless you add it to a group
tokens:manage	Tokens, panel accounts, and the audit log
code	Java scripts. Only owner has it

Nobody hands out more than they have: an admin can't make an owner token. GET /api/v1/auth/me tells a client what its token comes to.

commands:read came in 4.1.0. A config that lists its own groups gets it only where you add it; the default moderator, admin, and owner have it, viewer and anonymous visitors don't. A monitoring token built on viewer stays as it was.

Tokens from 2.x keep working: read means viewer, write:world and write:players mean world:write and players:write, and admin is the group.

Tokens in config.yml

For automated setups, tokens can also live in config.yml. Make each one 64 random hex characters, for example with openssl rand -hex 32:

auth:
  tokens:
    - name: site
      token: "<64 random hex characters>"
      scopes: [viewer]
    - name: agent
      token: "<another one>"
      scopes: [viewer, "world:write", "players:write"]
      rateLimit: { requestsPerMinute: 600, burst: 100 }

/worldapi reload applies them. A token from the config can't be revoked from the menu; remove it from the file.

What visitors without a token see

auth.anonymous.endpoints lists the paths visitors may read; they can never write. privacy.anonymous keeps coordinates, inventories, IP addresses, and chat from them, all off by default. websocket.anonymousTopics lists the live topics they may follow. See Configuration.

Next: Admin panel.