Repository navigation
WorldAPI token
Without a token the exporter reads what WorldAPI shows to every visitor: the server, performance, worlds, online players, statistics, and events. A token opens more, permission by permission.
| Permission | What it adds |
|---|---|
server:read |
Plugins and their versions, and what crowds each world: items on the ground, villagers, pets, named mobs, the busiest chunks with their hoppers |
players:private |
Where each online player stands |
chat:read |
Chat messages, in all and per player. WorldAPI also needs events.chat: true in its config to record chat |
system:read |
The host: load, memory, swap, the disk under the server folder, container limits, open files, the process's memory, Java |
logs:read |
Console lines by level, and warnings and errors by who logged them |
players:moderate |
Bans, operators, and the whitelist. This permission also bans and kicks, so leave it out unless you need the counts |
Metrics names the permission behind each metric.
-
Generate 64 random hex characters:
openssl rand -hex 32
-
Add a token to WorldAPI's
config.yml, underauth.tokens:auth: tokens: - name: monitoring token: "the 64 characters from step 1" scopes: [viewer, "logs:read", "system:read"]
The
viewergroup holdsserver:read,players:read,players:private,events:read, andchat:read. Together withlogs:readandsystem:read, the token reads everything the exporter uses except moderation, and changes nothing. -
Restart the server, or run
/worldapi reload. -
Pass the token to the exporter as
WORLDAPI_TOKEN, or put it in a file and pointWORLDAPI_TOKEN_FILEat it. In the targets file, usetokenortoken_file. -
Check
minecraft_exporter_endpoint_allowedon/metrics:1for each endpoint the token opens,0for each it doesn't.
The exporter asks a closed endpoint again every 10 minutes, so a permission you add later shows up without a restart. A refusal never counts as an error.
A token also gets WorldAPI's limit for tokens, 1200 requests a minute by default instead of 120 for a visitor, so the exporter refreshes statistics in bigger batches.
Warning
With a token the exporter publishes what WorldAPI hides from visitors: where every player stands, who chats how much, the console's warnings, the machine itself. Anyone who reaches /metrics, your Prometheus, or a Grafana with these metrics reads all of it. A Grafana data source holding the same token reads everything the token may, chat messages included.
- Keep the exporter, Prometheus, and Grafana behind a login or a firewall, never on a public address.
- Turn Grafana's anonymous access off.
- Give the token read permissions only. Never give it a write permission: Grafana's Infinity data source can send POST requests.
- The exporter never logs the token.
Next: Prometheus.
For server owners
For developers