The local API and keys

Keystone answers HTTP on 127.0.0.1:25586. The panel is one caller; your own tooling can be another.

[api]
enabled = true
address = "127.0.0.1"
port = 25586
reachable-at = ""     # 0.1.1 and newer

Loopback is the default and it is the safe one. Anything else is reachable by whoever can reach that machine, and the API can do everything the mod can do. If you need it from another machine, put it behind an SSH tunnel rather than binding it to the world.

reachable-at does not decide where it listens — it decides which address the mod writes into the editor link and into openapi.json. In detail on the panel page.

Keys

/keystone key new <name> <scope> [scope ...]
/keystone key list
/keystone key revoke <id>

A key is printed once, when it is made, and never again — the same way a person sees a password. Every key has a name, so the audit trail says who did what, and a rate limit per minute.

Authorization: Bearer <key> on every call. No key, or a key without the scope, answers 404 rather than 403: a route that says "forbidden" has told an unauthenticated caller that it exists.

Scopes

A key carries the scopes it is given and nothing else. Asking for a scope this server has nothing behind is refused, and the refusal lists what does exist — so a typo is caught when the key is made rather than when it is used.

Scope	Reaches
status.read	Whether the server is up, who is on, how it is doing.
players.read	The people — including which game accounts one Discord user has linked.
permissions.read · permissions.write	Groups and what they may do.
operations.read · operations.run	The timetable, and running one by hand.
settings.read · settings.write	Every setting.
console.read	The server's log.
chat.read	What is being said.
events.read	The live stream (below).
audit.read	Who changed what.
keys.read	Which keys exist — never their secrets.
backup.read · backup.restore	Backups, and putting one back.
perks.read · perks.write	What people have earned.
assistant.read · assistant.write	The in-game assistant.
server.read	The machine underneath.

Give a key the narrowest set that does the job. A monitoring script wants status.read and nothing else.

What is there

GET /v1/openapi.json lists every path this server actually has — the mod writes that document out of its own routes, so it cannot be wrong about what exists. When you want the list, ask the server rather than this page.

Roughly: /v1/status, /v1/players (plus /v1/players/group, /v1/players/perk, /v1/players/check, /v1/players/grants), /v1/groups, /v1/operations (/run, /cancel, /history), /v1/backups (/restore), /v1/settings (/history, /rollback), /v1/console, /v1/chat, /v1/events, /v1/audit, /v1/keys, /v1/bans, /v1/tickets, /v1/votes, /v1/skins, /v1/progress, /v1/metrics (/history), /v1/bench, /v1/catalog, /v1/entities, /v1/gate (/maintenance), /v1/accounts, /v1/discord (/links), /v1/assistant/* and /v1/reload.

The live stream

GET /v1/events with events.read holds the connection open and writes server events down it as they happen — which is what makes the panel a panel rather than a page you refresh. It is authenticated like everything else, and answers 404 without a key.

Addons on the JVM

If you are building an addon in Java you do not talk over HTTP — you compile against keystone-api, which travels inside that same jar (META-INF/jarjar/) and has no dependencies of its own, not even a logging framework. It is how you register your own module, command, permission or source of ranks.

What is written down

Every change through the API is an audit line: who, what, when. Sensitive commands are masked out of it, the console and the log — Keystone's own automatically, and anything you name in keystone.mask-commands.