Skip to content

WorldAPI token

Pavel Erokhin edited this page Oct 20, 2026 · 2 revisions

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.

What each permission adds

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.

Make a read-only token

  1. Generate 64 random hex characters:

    openssl rand -hex 32
  2. Add a token to WorldAPI's config.yml, under auth.tokens:

    auth:
      tokens:
        - name: monitoring
          token: "the 64 characters from step 1"
          scopes: [viewer, "logs:read", "system:read"]

    The viewer group holds server:read, players:read, players:private, events:read, and chat:read. Together with logs:read and system:read, the token reads everything the exporter uses except moderation, and changes nothing.

  3. Restart the server, or run /worldapi reload.

  4. Pass the token to the exporter as WORLDAPI_TOKEN, or put it in a file and point WORLDAPI_TOKEN_FILE at it. In the targets file, use token or token_file.

  5. Check minecraft_exporter_endpoint_allowed on /metrics: 1 for each endpoint the token opens, 0 for 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.

Keep the metrics of a token private

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.

Clone this wiki locally