REST API Reference

Authentication

There are two ways to authenticate against /api/*. Browser sessions and the dashboard rely on the cookie + CSRF flow; the desktop app, scripted clients, and custom integrations use the Bearer header.

Cookie + CSRF (browser sessions)

POST /api/auth/login sets two cookies:

• auth-token — HttpOnly, SameSite=Lax, Secure when served over HTTPS. The middleware reads this first and treats it as a logged-in session. JavaScript can't see it.
• csrf-token — readable by JavaScript. Echo its value back as the X-CSRF-Token header on every state-changing request (POST/PUT/PATCH/DELETE). The backend signs the token and rejects mismatches with 403 csrf-mismatch.

Browser clients should send fetch requests with credentials: 'include':

const res = await fetch('/api/servers/123/restart', {
  method: 'POST',
  credentials: 'include',
  headers: { 'X-CSRF-Token': getCookie('csrf-token') },
});

Paths exempt from CSRF (no X-CSRF-Token required):

• POST /api/auth/login, POST /api/auth/logout
• All /api/setup/*
• GET /api/health
• POST /api/store/webhook (signed by Paddle)
• POST /api/discord/action (signed by the Discord bot — see Discord bot doc)

Bearer token (desktop / scripted clients)

The same POST /api/auth/login returns a JWT in the response body. Custom or scripted clients pass it as a Bearer header:

Authorization: Bearer <jwt-token>

The middleware reads cookie first and falls back to Bearer, so a single login can drive either flow. Bearer is the right choice when credentials: 'include' isn't an option (CLIs, native apps, server-to-server proxies).

Endpoints

Request (login):

{
  "username": "admin",
  "password": "your-password"
}

Response (login):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "1", "username": "admin", "role": "admin" }
}

The Set-Cookie headers on the same response carry auth-token and csrf-token for browser flows.

Servers

Server Control

RCON & Players

Admin Actions

These actions route through the Provider System (InHouseProvider → Sidecar, or RCON fallback).

Vehicle Actions

World Actions

Global Ban Database

Centralized ban system with UUID-based shareable ban IDs. Bans apply to all servers and are automatically synced to each server's ban.txt on start/restart.

Import format (POST body is a JSON array):

[
  {
    "steamId": "76561198012345678",
    "playerName": "PlayerName",
    "reason": "Cheating",
    "bannedBy": "admin",
    "bannedAt": "2026-03-05T12:00:00.000Z"
  }
]

Export response (download as citadel-bans-YYYY-MM-DD.json):

[
  {
    "id": "a1b2c3d4-...",
    "steamId": "76561198012345678",
    "playerName": "PlayerName",
    "reason": "Cheating",
    "bannedBy": "admin",
    "bannedAt": "2026-03-05T12:00:00.000Z",
    "source": "manual"
  }
]

Mods

Configuration

Backups

Config Backups

Deployment & Dangerzone

Files

Items & Types Editor

Logs & Metrics

Priority Queue (VIP)

Automated VIP system that syncs entries to DayZ's native priority.txt file. Players in the queue get priority position in the login queue. Entries support time-limited expiration and are automatically cleaned every 60 seconds.

Add entry example:

{
  "steamId": "76561198012345678",
  "name": "PlayerName",
  "role": "VIP",
  "expiresAt": "2026-04-06T23:59:59.999Z"
}

Roles: VIP, Supporter, Premium

Expiration: Set expiresAt to an ISO date string for time-limited VIP, or null for permanent access.

Import format (POST body is a JSON array):

[
  {
    "steamId": "76561198012345678",
    "name": "PlayerName",
    "role": "VIP",
    "expiresAt": null,
    "addedBy": "admin"
  }
]

Webhooks

Notifications

Users & Roles

License

Cloud Integration

Steam & Workshop

VIP Store

System

Health

Audit

Scheduler

Watchlist

Additional Endpoints

Integrations / Discord bot

These endpoints are how the official Citadel Discord bot drives the controller. They have their own auth contract — see the Discord Bot guide for the full 3-layer security model.

POST /api/discord/action

Executes a Discord-initiated action against a Citadel server. The bot signs each call with HMAC-SHA256 over (timestamp, action, discordUserId) using the shared bot secret.

Headers:

Authorization: Bearer <DISCORD_BOT_API_KEY>
X-Discord-Ts:  <unix-seconds>
X-Discord-Sig: <hex-hmac-sha256>

Body:

{
  "action": "server.restart",
  "discordUserId": "242109987654321098",
  "discordUserTag": "moderator#0001",
  "serverId": "srv_4f3a",
  "params": { /* action-specific */ }
}

The backend resolves the calling Discord user against data/discord-user-roles.json (Layer 3) → falls back to the built-in discord-bot role (Layer 1). If the resulting role doesn't grant the permission ACTION_PERMISSIONS[action] requires, the call is rejected with 403 and a discord.denied audit row.

Stale or replayed signatures (timestamp older than the configured window, or HMAC mismatch) return 403 with discord.sig-rejected. Calls that don't carry the HMAC headers at all still execute (legacy bots) but get tagged as "Discord Bot (unverified)" in the audit log.

Per-Discord-user role mapping

Rate limits

The API enforces a per-IP global cap plus tighter scoped caps on auth and bot paths. All limits are per-IP (not per-user) and use a 1-minute sliding window unless noted.

A request that trips a limit returns 429 Too Many Requests with a Retry-After header in seconds.

Login lockout

Failed sign-ins are tracked per (IP, username) rather than per-username alone, so an attacker who knows a target's username can't lock that account from arbitrary IPs. Five failures within 10 minutes from the same (IP, username) triggers a fail2ban-style escalating ban: first lockout 60s, second 5min, third+ 1h. A successful sign-in clears the counter.

This means: you'll never get locked out of your own account because someone else is spamming wrong passwords for it from a different IP.