Web Dashboard API

Overview

XBans registers a WebModule with the XCore web dashboard, providing REST API endpoints for managing sanctions through the web interface. This allows server administrators to review and manage moderation data from a browser without being in-game.

Authentication

All API endpoints require a valid Bearer token in the Authorization header. Tokens are managed through the XCore web panel.

Authorization: Bearer <your-token>

Authentication uses constant-time token comparison to prevent timing attacks. Unauthenticated requests receive a 401 Unauthorized response.

API Endpoints

All XBans endpoints are prefixed with /api/xbans. Read endpoints are GET; write endpoints are POST with a JSON body.

Read endpoints

Method	Endpoint	Description
GET	/api/xbans/stats	Sanction counts (active bans, mutes, warns, reports, jails, totals)
GET	/api/xbans/bans	List all active bans
GET	/api/xbans/ip-bans	List all active IP bans
GET	/api/xbans/mutes	List all active mutes
GET	/api/xbans/ip-mutes	List all active IP mutes
GET	/api/xbans/warns	List all active warnings
GET	/api/xbans/reports	List all reports
GET	/api/xbans/jails	List all jailed players
GET	/api/xbans/jaillist	List configured jail locations
GET	/api/xbans/watchlist	List watchlisted players
GET	/api/xbans/players	List all known players
GET	/api/xbans/player/:uuid	Get a player's sanction profile
GET	/api/xbans/audit	Audit log (paginated, searchable, filterable)

Write endpoints

Issue or lift sanctions through the API. Body parameters typically include uuid, reason, duration (optional), and moderator.

Method	Endpoint	Description
POST	/api/xbans/ban / /unban	Issue / lift a ban
POST	/api/xbans/ban-ip / /unban-ip	Issue / lift an IP ban
POST	/api/xbans/mute / /unmute	Issue / lift a mute
POST	/api/xbans/mute-ip / /unmute-ip	Issue / lift an IP mute
POST	/api/xbans/warn / /unwarn	Issue / lift a warning
POST	/api/xbans/kick	Kick an online player
POST	/api/xbans/jail / /unjail	Jail / release a player
POST	/api/xbans/freeze	Toggle freeze on a player
POST	/api/xbans/note/add / /note/delete	Add / delete staff notes

All responses are JSON. List endpoints support pagination via ?page=1&limit=50 query parameters.

CORS & Rate Limiting

The API handles CORS automatically through XCore's web panel helpers. OPTIONS preflight requests are handled for cross-origin browser access.

Rate limiting is enforced per IP address:

• 30 requests per 60-second window
• Exceeding the limit returns 429 Too Many Requests

Cross-Server Sync

When a POST endpoint modifies sanction data (e.g., unbanning a player from the web panel), XBans automatically handles cross-server synchronization. The SanctionCache calls notifySync() internally, so the change is reflected on all connected servers immediately.