Skip to main content

Authentication

Every request to the Zander API must be authenticated. The mechanism is simple: a single shared key configured once in your .env file and referenced in each plugin's config.yml.

API Key​

The Zander API uses a shared API key for all requests from Minecraft plugins and other backend consumers.

Set the key in your .env file:

apiKey=your-secret-api-key-here

The same key must be added to each plugin's config.yml:

APIKey: "your-secret-api-key-here"

Sending Requests​

Include the API key in the x-access-token request header:

GET /api/user/get?username=Steve HTTP/1.1
Host: example.com
x-access-token: your-secret-api-key-here

Bearer token variant (plugin ingestion endpoints)​

Some plugin-to-server ingestion endpoints - notably the Mixed module's /api/mixed/* ingestion routes used by the zander-pgm plugin - accept the same apiKey value presented as a standard Authorization: Bearer header instead of x-access-token:

POST /api/mixed/events/batch HTTP/1.1
Host: example.com
Authorization: Bearer your-secret-api-key-here
Content-Type: application/json

Both header forms are checked against the same apiKey value - there is no separate per-module token. Some endpoints (e.g. Mixed vote/rating submission) accept either a valid web session or a valid plugin token, since the action can originate from a browser or from the plugin relaying a player's in-game action; when authorized via plugin token, player identity comes from the request body rather than the session.

Error Responses​

If the header is missing or the token does not match, the API returns:

Missing token:

{
  "success": false,
  "message": "No token provided."
}

Invalid token:

{
  "success": false,
  "message": "Invalid token."
}

Feature-Gated Endpoints​

Some endpoints also check whether their associated feature is enabled in features.json. If a feature is disabled, the endpoint returns:

{
  "success": false,
  "message": "This feature has been disabled."
}

Web Session Authentication​

The web dashboard uses session-based authentication (cookie-based) managed by the express-session library with a Prisma store. This is separate from the API key and applies only to browser-based dashboard access.