API reference

Every route Yggdrasil Panel serves, what it does, and what it takes to call it. The web UI talks to this API and nothing else, so anything the UI can do, you can automate.

Authentication

Yggdrasil accepts two kinds of credential, and one endpoint reads them in a fixed order:

1. Authorization: Bearer <token> — the header wins if present.
2. The ygg_token cookie.
3. The ?token= query parameter.

Session cookie

POST /api/auth/login with {"username", "password"} (plus "code" when the account has TOTP enabled) returns a signed JWT and sets it as a ygg_token cookie. The cookie is HttpOnly, SameSite=Strict, path /, and lives for the configured session TTL. The same JWT is also returned in the response body.

Every request carrying a JWT is re-checked against the database: the panel reads the user’s current role, refuses the request if the account is disabled, and refuses it if the token’s version no longer matches the account’s token_version. That last check is what makes POST /api/auth/logout a real revocation — it bumps token_version, invalidating every JWT ever issued to that user. Because the role is read live, a demotion takes effect on the next request rather than at token expiry.

API tokens

For automation, mint a token with POST /api/tokens and a body of {"name": "..."}. The response contains the plaintext token exactly once:

{"id": "…", "name": "home-automation", "token": "ygg_…"}

Only a hash is stored, so a lost token cannot be recovered — delete it and mint another. Tokens start with ygg_, which is how the auth middleware tells them apart from JWTs. Send one as Authorization: Bearer ygg_…. GET /api/tokens lists your own tokens with their last-used timestamp; DELETE /api/tokens/{id} removes one, and you may only delete your own.

Read Gotchas before you hand an API token to anything. A token is not a scoped credential.

WebSocket handshakes

Browsers cannot set headers on a WebSocket handshake, so the three streaming endpoints also accept ?token=<jwt-or-api-token> in the query string. The access log redacts token, access_token, and api_key query parameters, so a token in a URL does not land in journald — but it does travel in the request line, so prefer the cookie from a browser and the query parameter only where you have no alternative.

Cross-origin requests and CSRF

The panel serves its own UI, so it never needs credentialed cross-origin access. CORS allows any origin but never reflects credentials, and the allowed headers are Accept, Authorization, Content-Type, and X-CSRF-Token.

On top of SameSite=Strict, the auth middleware rejects POST, PUT, PATCH, and DELETE whenever the request carries an Origin header whose hostname differs from the request’s host. The response is 403 {"error": "cross-origin request blocked"}. A browser on the panel’s own origin matches and passes. Bearer automation — curl, a script, a home assistant — sends no Origin at all, so the check does not apply to it. The WebSocket upgrader applies the same rule: an empty Origin or a same-host one is accepted, anything else is refused.

Login rate limits

POST /api/auth/login is limited to 5 attempts per IP per minute; over that you get 429 {"error": "too many login attempts"}. The client IP comes from the real-IP middleware, so a reverse proxy’s X-Forwarded-For is honoured.

Because a spoofed X-Forwarded-For would sidestep a purely IP-based limit, there is a second, per-account lockout: 10 failed attempts on one username within 15 minutes locks that username for 15 minutes, regardless of source IP, with 429 {"error": "account temporarily locked due to repeated failed logins; try again later"}. A successful login clears the counter. A wrong password, an unknown username, a bad TOTP code, and a replayed TOTP code all count as failures.

Permissions

A user is either a global admin or a delegate. Admins bypass every check in the panel — the permission helpers return true for them before any grant is loaded, and requireAdmin routes accept them unconditionally.

Everyone else holds grants. A grant is a set of permissions attached to one scope. There are eight permissions:

And four scopes a grant can hang off:

A check passes when any single grant both contains the permission and covers the target. So a server.control grant at realm scope lets you restart every server in that realm; a server.files grant at gameskill scope lets you edit files on every DayZ server you can see, wherever it lives. List endpoints filter rather than refuse: GET /api/servers returns only servers you can view, and GET /api/domains and GET /api/schedules filter the same way.

Denied requests return 403 {"error": "forbidden: insufficient permissions"}. requireAdmin returns 403 {"error": "forbidden"}.

Rune management, realm mutations, user management, and every integration setting are admin-only — a rune controls the Docker runtime (image, command, user, capabilities, devices, mounts), so uploading one is equivalent to root on the host.

Gotchas

Two behaviors here will not match what you assume from the shape of the API. Both are worth reading before you build against it.

API tokens carry no scope of their own

An ygg_ token is not a scoped credential. It is a pointer to a user. When the middleware sees the ygg_ prefix it looks the token’s hash up in api_tokens, joins to the owning user, and builds claims from that user’s id, username, and current role. There is no per-token permission subset and no way to create one: a token minted by an admin is an admin token, and it passes every requireAdmin route — user management, rune upload, system update, the lot. A token minted by a delegate carries exactly that delegate’s grants, no more and no less. If you want a narrow automation credential, create a user with narrow grants and mint the token as that user.

The token lookup filters on disabled=0, so disabling an account does immediately kill its tokens.

Logout does not revoke API tokens

The token_version mechanism that makes logout revoke JWTs does not reach API tokens. The claims built for an ygg_ token omit the version field entirely, and the API-token branch of the middleware returns before the code that compares a token’s version against the account’s. Bumping token_version — which is all POST /api/auth/logout does — therefore has no effect on any ygg_ token. Logging out everywhere leaves every API token live.

To revoke an API token, delete it: DELETE /api/tokens/{id}. To revoke all of a user’s tokens at once, disable or delete the user.

A delegate can create a schedule they cannot then touch

POST /api/schedules is permission-checked. For a server-scoped schedule it requires server.schedule on that server, plus the permission the scheduled action would need if you ran it by hand: server.console for a command, server.control for start/stop/restart/update/wipe, server.backup for a backup. A rendered player message needs nothing beyond server.schedule. The table is exhaustive and fails closed — an action with no entry is rejected. Realm- and global-scoped schedules are admin-only.

The other three mutations are not permission-checked. PUT /api/schedules/{id}, DELETE /api/schedules/{id}, and POST /api/schedules/{id}/run are flat admin-only and return 403 {"error": "admin required"} for everyone else, with no consideration of grants.

So a delegate with server.schedule and server.control on a server can create a nightly restart, see it in GET /api/schedules, and read its history at GET /api/schedules/{id}/runs — but cannot edit its cron expression, cannot disable it, cannot delete it, and cannot trigger it early. Only an admin can do those.

Conventions

Everything is JSON in and JSON out, with Content-Type: application/json.

Errors are a flat object with a single key, returned with the matching HTTP status:

{"error": "forbidden: insufficient permissions"}

JSON request bodies are read through a 1 MiB limit. The reader truncates at the cap rather than returning a distinct error, so an oversized body surfaces as 400 {"error": "invalid request"} from the decode. This applies to the pre-auth login endpoint too, which is the point: an unauthenticated client cannot exhaust memory. A few endpoints have their own limits — rune upload caps the body at 512 KB, file upload is multipart with a 64 MiB form buffer, and the file editor refuses to open anything over 5 MB.

There is deliberately no global request timeout. The console, log, and install streams are long-lived, and container operations like an image pull or a first start can run for minutes; a blanket timeout dropped both. Individual operations carry their own contexts instead — the AI planner, for instance, gives the model 60 seconds.

Responses set X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: strict-origin-when-cross-origin, and a strict CSP. HSTS is asserted only when the request arrived over TLS or through a proxy that set X-Forwarded-Proto: https, so plain-HTTP LAN access does not lock you out.

Worked example

Mint a token in the UI under Settings → API tokens, or over the API from an existing session. Then list your servers:

curl -s -H "Authorization: Bearer ygg_XXXXXXXX" \
  https://panel.example.com/api/servers

Each entry carries the server’s id, name, rune, status, allocated ports, tags, and more. Abridged:

[
  {
    "id": "3f9c…",
    "name": "survival",
    "gameskill_id": "minecraft-java",
    "status": "stopped",
    "ports": {"game": 25565, "rcon": 25575},
    "perms": ["server.view", "server.control", "server.console"]
  }
]

The perms array on each server is the caller’s effective permissions on it — useful for deciding what to attempt. An admin always gets all eight. Start one:

curl -s -X POST -H "Authorization: Bearer ygg_XXXXXXXX" \
  https://panel.example.com/api/servers/3f9c…/start

No Origin header goes out, so the same-origin mutation check does not apply. Follow the console:

websocat "wss://panel.example.com/api/servers/3f9c…/console?token=ygg_XXXXXXXX"

Route reference

The Auth column names the strictest requirement. “Session” means any authenticated caller, JWT or API token. “Admin” means a global admin. A permission name means that permission on the target server, which an admin also satisfies.

Public

These need no credential at all. The status and beacon routes 404 rather than 403 when their feature is switched off, so a disabled status page or beacon receiver is not advertised.

Session and account

Claude connector (MCP)

The panel speaks the Model Context Protocol at /api/mcp so Claude can read and drive it — see Claude connector. The endpoint is Streamable HTTP: a JSON-RPC message in a POST, one JSON object back, no server-initiated stream (GET and DELETE answer 405, which is how the transport spec says to advertise that).

Authorization is OAuth 2.1 with the panel as its own authorization server, so a client registers itself and the user approves it in a browser. Those endpoints are public by necessity — they are what a client uses before it has a token — and grant nothing until someone presses Allow.

An unauthenticated request to /api/mcp answers 401 with WWW-Authenticate: Bearer resource_metadata="…", which is how a client discovers the flow.

Runes

The API spells a rune gameskill. Reading the catalogue is open to any session because the create-server form needs it; everything that changes the catalogue is admin-only.

Moving a large server between panels — pull, don’t push. An export streams, so downloading a multi-gigabyte server works through a tunnel. An upload is a request body, and Cloudflare caps those at 100 MB (Free/Pro), so pushing a real data directory up through a tunnel cannot work regardless of what the panel allows. POST /api/panel/remote/import inverts the direction: the receiving panel fetches the bundle itself, which is a large response and is not capped, and the browser never carries the data. If both panels share a Tailscale/VPN, give the private address and the copy skips the internet entirely. Two cautions: the bundle carries decrypted secrets, so pull over HTTPS or a private network; and because the panel fetches an operator-supplied URL, these routes are admin-only and audited — they cannot be host-allowlisted, since reaching private addresses is the point.

The GitHub routes read public repositories anonymously. To browse and install from a private one — or to lift GitHub’s 60-requests-per-hour anonymous limit — store a token via PUT /api/settings/github; it is then sent as a Bearer credential on GitHub’s own hosts only. Note that GitHub answers 404 (not 403) for a private repository the caller cannot see, so a listing that fails without a token is usually a permissions problem rather than a wrong path.

Servers

Fleet

Cross-server aggregates for the Dashboard. These are not RBAC-filtered per server: they either return whole-fleet numbers or, in the case of /fleet/activity, merge the audit log with every server’s history — which is why that one is admin-gated and the others return only aggregates.

Host migration

Move things between two running panels. Both bundle formats carry secrets in recoverable form (the target re-encrypts them with its own key), so every route is admin-only and the files should be treated like passwords.

Players and moderation

Player actions run over RCON, so they gate on server.console rather than server.control.

Files

All of these resolve the server’s data directory and gate on server.files. Paths are jailed to that directory, including through symlinks.

The editor keeps 10 versions per file and only snapshots UTF-8 files up to 256 KB.

Mods and plugins

Minecraft mods and plugins, resolved against Modrinth. Reading gates on server.view; anything that writes a jar gates on server.files, because that is what it is doing. Mods take effect on the next restart, which is a recreate — the API says so rather than letting a caller assume it took.

Backups

Backup targets are global configuration and admin-only. Individual backups gate on server.backup for the server they belong to — for /api/backups/{id}/… the panel resolves the backup’s server first, then checks.

Schedules and templates

Read Gotchas — the gates here are not symmetric.

Managed schedule rows — the ones behind the per-server auto-restart toggle — are hidden from GET /api/schedules and driven through /api/servers/{id}/auto-restart instead.

Users, realms, and permissions

Listing realms is open to any session because the create-server form needs it. Every other route here is admin-only: a realm is a permission scope, so renaming or deleting one moves servers between grant boundaries.

Kvasir

Kvasir’s features are opt-in and off until an admin configures a provider. Configuration is admin-only; the advisory endpoints gate on the permission that matches what they reveal.

/api/ai/plan and /api/ai/plan/execute need no explicit permission because they scope themselves: both build the candidate set from the servers the caller holds server.control on, and the execute step re-derives that set server-side rather than trusting the posted plan. Both refuse with 400 unless an admin has enabled AI actions.

Watchers

Log-pattern rules scanned against running servers’ container logs (see the monitoring guide). All admin-only — watchers read logs across servers.

IP blocking

Blocks an abusive client IP at Cloudflare’s edge (when a zone the panel’s token can see owns the site’s hostname) or in the host firewall via nftables (for a directly-exposed site). Admin-only. Private, loopback, link-local, Tailscale/CGNAT and Cloudflare’s own ranges are always refused, and the nftables rules only ever touch ports 80/443 — never SSH.

Norn

Norn is the DayZ loot-economy tool. Reading the economy needs server.view; changing it needs server.control, because these routes rewrite mission files.

Networking and domains

The domain list is RBAC-filtered like the server list. Every integration setting is admin-only.

GET /api/settings/network is readable by any session because the connect address is what the UI shows players; writing it is admin-only.

Steam

Status page, beacon, and Discord

The public status board caches for 15 seconds and is served with Cache-Control: public, max-age=15.

Notifications

Audit

System

Anything not matching /api/ falls through to the embedded SPA, which serves index.html for unknown paths so client-side routes deep-link correctly. Unknown /api/ paths return 404.

WebSocket endpoints

Four endpoints upgrade to WebSocket. All four authenticate exactly like the rest of the API — the ygg_token cookie is enough from a browser, and ?token= carries a JWT or an ygg_ API token from anything that cannot set headers. The upgrader accepts a handshake with no Origin (automation) or one whose hostname matches the request host, and refuses everything else.

/console is the one that writes, which is why it gates on server.console while /logs needs only server.view. Each message you send it is one command: it goes over RCON when the server’s rune declares an enabled rcon block, and to the container’s stdin otherwise. Start an install with POST /api/servers/{id}/install and follow /install/log for progress; the install itself runs in the background and does not block the POST.

See also

• Rune schema