Authentication & Rate Limits

One key, one header, a shared rate limit. Here's the whole model.

The key model

Your API key is personal — it's tied to your Minecraft account, not to the server, and not to any particular bot or project. There is no concept of separate "app keys" or scoped credentials.

If you run multiple bots

They currently all share your one key. There's no per-bot key issuance today, so if you run a stats bot and an auction bot, both use the same X-API-Key value — and both count against the same rate limit (see below).

Rate limits

Requests are rate-limited per key on a fixed time window. The default is commonly 60 requests per minute, but server admins can change this — treat 60 as a typical starting point, not a guarantee. If your bot's traffic is anywhere near the limit, ask the server's staff what the current number actually is rather than hardcoding it.

When you exceed it

You'll get an HTTP 429 with a Retry-After header (seconds to wait) and a JSON error body, for example:

http 429 Too Many Requests

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"error": "Rate limit exceeded. Try again later."}

The right response is to back off and retry after the indicated delay — not to immediately retry or hammer the endpoint. A minimal backoff looks like this:

javascript

async function apiGet(path, apiKey) {
  const res = await fetch(`${API_BASE}${path}`, {
    headers: { "X-API-Key": apiKey }
  });

  if (res.status === 429) {
    const waitSeconds = Number(res.headers.get("Retry-After")) || 60;
    throw new RateLimitError(waitSeconds);
  }

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(body.error || `Request failed with ${res.status}`);
  }

  return res.json();
}

class RateLimitError extends Error {
  constructor(retryAfterSeconds) {
    super(`Rate limited, retry after ${retryAfterSeconds}s`);
    this.retryAfterSeconds = retryAfterSeconds;
  }
}

See the Discord.js example for how to surface a 429 to a Discord user gracefully instead of letting the command silently fail.

Key revocation

Server staff can revoke an individual key at any time with /api revoke <player> — typically because a bot using that key is misbehaving (hammering the API, scraping excessively, etc.).

Sudden 401s?

If a key that was working fine suddenly starts returning 401 Unauthorized with no code changes on your end, revocation by staff is the most likely cause. Run /api key in-game to check — if it prints a different key than the one you're using, you'll need to update your bot's config. If you actually leaked the key yourself, use /api regenerate instead.

A key can look up any player

This is intentional, not a bug: your API key isn't scoped to "your own" data. You can query /api/player/{name-or-uuid} for any player on the server, not just yourself. That's what makes leaderboard bots, "check so-and-so's stats" commands, and auction-alert bots possible in the first place — there would be no way to build those features if keys were locked to their own owner's data.