Web dashboard

Commands 4#

/dashboard status
/dashboard start
/dashboard url

/apikey create farmstead-dash ADMIN
/apikey list
/dashboard status

/dashboardregister start
/dashboardregister complete steve_admin S3cretPass
/dashboardregister status

/dashboardregister discord
/dashboardregister status

/dashboard pair "https://dash.example.com" ABCD1234
/linkaccount K7MNPQ2R
/dashboard unpair

Permissions 4#

Detailed guide#

Version: 1.0.5+build.54 · Config: config.json → webDashboard section (dashboard on/off is controlled by both webDashboard.enabled and modules.webDashboardEnabled — either one set to false disables it)

Overview#

NeoEssentials runs an embedded HTTP server (plus a WebSocket server for live updates) exposing a full REST API for server monitoring and administration. There are now two ways to actually use it, controlled by webDashboard.mode:

• "external" (the shipped default) — the mod serves only /api/*; a separately-hosted dashboard app (the NeoEssentials-Dashboard Laravel project) is the actual browser UI, talking to this API from outside. See API System and docs/API.md for the full REST/WebSocket reference it's built against.
• "internal" / "both" — the mod serves its own bundled dashboard UI directly from /, no separate app to install at all. As of build.13 this internal UI is feature-complete and covers the same ground as the external app: Overview, Players (with a full per-player control page), Economy, Warps, Kits, Holograms, Discord, dashboard account management, Backups, Commands, Logs, Permissions, a public no-login player-lookup page, and (as of build.15) an account Settings page — see Account Settings & Minecraft Account Linking below. "both" is just an explicit alias for "internal", useful when you deliberately run the built-in UI and point an external app at the same API at the same time.

The account system, permission model, and moderation/economy/etc. backing data described below are shared by both dashboards — they're the same accounts and data either one authenticates against and reads/writes through the API.

Setup#

1. Set webDashboard.enabled: true and modules.webDashboardEnabled: true in config.json (both default to true)
2. Configure port (default 8080) and websocketPort (default 8081)
3. Start the server, then run /dashboard start (webDashboard.autoStart ships false, so the API server doesn't come up on its own unless you set autoStart: true)
4. Create a credential for whatever's going to call the API: - An external dashboard backend (recommended path): create an API key in-game — /apikey create <label> [role] — and give the printed token to that dashboard's server config. See API System → Authentication for the full picture. - A human dashboard account: register in-game via /dashboardregister start then /dashboardregister complete <username> <password> (or /dashboardregister discord if Simple Discord Link is linked) — or use one of the other paths below.
5. Point your external dashboard app at http://<server-ip>:<port>/api/... (port from step 2) using the API key or session token as a Bearer token.

Account Registration#

Players register their dashboard account in-game, via the separate /dashboardregister command (not a subcommand of /dashboard) — they do not need to be online at login time after registering.

/dashboardregister start
/dashboardregister complete <username> <password>

Or, if Simple Discord Link, Mc2Discord, or DCIntegration is installed and the player has linked their Discord account:

/dashboardregister discord

Requires permission neoessentials.dashboard.access. Registration tokens from start expire after 5 minutes; passwords must be at least 8 characters. Run /dashboardregister status to check your current registration state.

Other ways to get dashboard access:

1. API key (for an external dashboard backend, not a human) — /apikey create <label> [role] in-game, or POST /api/apikeys once a first key exists. Not a login account at all; see API System and docs/API.md.
2. Default admin account — the first time the dashboard starts with no accounts at all, an admin account is auto-created with a random temporary password, printed once to the server console/log (Temporary password: ...) and flagged to require a password change on first login. There is no fixed default password — check the boot log if you've lost it, or reset it via /api/users/{id}/password (admin session) if you still have another admin account.
3. Minecraft-permission login (self-service, works offline, deprecated) — on the login page, authenticate with just your Minecraft username (no password). The server checks whether that player has neoessentials.dashboard.access and auto-creates an account with role assigned from neoessentials.dashboard.admin/.moderator/.access. Predates the /dashboardregister flow above and is marked deprecated in server logs, but still functional.
4. Discord OAuth (optional, self-service) — see below. If allowAutoRegistration: true (the default), logging in with Discord auto-creates an account on first use.
5. Admin-created accounts — an existing admin can create accounts directly via POST /api/users/create (or whatever user-management screen the external dashboard exposes for it), or push-sync one from the external dashboard's own user table with POST /api/users/sync — see docs/API.md.

Discord Auth (Optional)#

If a supported Discord companion mod — Simple Discord Link or Mc2Discord — is installed, players can link their Discord account, and the dashboard can source their Discord identity and roles from it. The mod is fully optional — standalone account registration works without it.

Discord-Linked Dashboard Identity#

NeoEssentials does not talk to Discord's API directly — no bot token, no OAuth2 code exchange, no REST calls to discord.com. All Discord communication is delegated entirely to whichever companion mod is installed (Simple Discord Link or Mc2Discord); NeoEssentials only reads the account-link data that mod already has.

How It Works#

Player links their account in-game (via SDLink's or Mc2Discord's own commands)
         │
         ▼
ChatIntegrationManager.findLinkedDiscordId(uuid)  ── checks whichever companion mod is ready
         │
         ▼
DiscordAuthProvider  ── resolves Discord ID + role IDs for that player
         │
         ▼
Dashboard: GET /api/auth/discord?username=<name>
  1. Look up the linked Discord account
  2. Check blacklist / whitelist roles
  3. Map Discord roles → dashboard role
  4. Get-or-create dashboard user, create session

There is no "Login with Discord" OAuth2 button — a player must first link their account in-game through Simple Discord Link's or Mc2Discord's own linking flow.

Companion mods#

Detection is purely runtime (ModList.isLoaded(...)) — neither mod is a hard dependency, and NeoEssentials works fine standalone if neither is installed.

Config (discord_auth.json)#

Located at config/neoessentials/discord_auth.json. Auto-generated on first start.

Role mapping

Discord role IDs (not names) are mapped to dashboard roles. Enable Developer Mode in Discord Settings → Advanced, then right-click a role → Copy ID.

"roleMapping": {
  "123456789012345678": "ADMIN",
  "234567890123456789": "MODERATOR",
  "345678901234567890": "VIEWER"
}

Whitelist / Blacklist

"whitelistedRoles":  ["123456789012345678"],   // only these role IDs can log in (empty = everyone)
"blacklistedUsers":  ["987654321098765432"]    // these Discord user IDs are always denied

Without a Discord companion mod#

If none of SDLink, Mc2Discord, or DCIntegration is installed, GET /api/auth/discord returns 503 — Discord-linked login is unavailable entirely (there's no account-link data to read). Standalone username/password login is unaffected.

Troubleshooting#

Config (config.json → webDashboard)#

The dashboard's on/off switch is now split across two keys that both have to allow it: webDashboard.enabled (this section) and modules.webDashboardEnabled (the mod-wide modules block at the top of config.json, alongside economyEnabled/chatEnabled/etc.). Either one set to false disables the whole dashboard.

The apiSettings, uiSettings, loggingSettings, enableCORS, and maxThreads keys from earlier documentation do not exist in the current codebase — the dashboard's security-related settings live entirely under securitySettings, and there is no config option to disable REST endpoints or config editing independently.

What the Dashboard Can Do#

Both the internal (bundled) and external (Laravel) dashboards cover the same 13 pages, since both are built against the same REST API: Overview (/api/stats + /api/server), Players + full per-player control page (/api/player + /api/moderation), Economy, Warps, Kits, Holograms, Discord, dashboard account management (/api/users), Backups, Commands/console (/api/commands), Logs (/api/logging), Permissions (/api/permissions), and a public no-login player-lookup page. Full endpoint detail in API System → docs/API.md.

Account Settings & Minecraft Account Linking#

Both dashboards have an account Settings/Profile page (the internal one gained this in build.15; it was previously just a disabled "not yet ported" placeholder) covering:

• Change password — same on both dashboards.
• Link a Minecraft account — new this pass, and the first way to do this without needing Discord: the Settings page generates a short one-time code, and you type /linkaccount <code> in-game to confirm ownership. Works for any dashboard account regardless of how it was created (self-registered, admin-created, or via /dashboardregister). Self-service unlink is also available. See docs/API.md's /api/auth/link-minecraft/* routes.
• Discord status — read-only on the internal dashboard (resolved via whichever Discord companion mod is installed — see below); the external dashboard keeps its existing full OAuth2 "Connect Discord" flow. A genuine browser-initiated Discord OAuth2 flow for the internal dashboard (so it gets the same "Connect Discord" button) is a planned follow-up, not built yet — the mod deliberately doesn't perform Discord OAuth2 itself today (see DiscordAuthProvider's own doc comment).
• Once linked, the sidebar's user avatar on both dashboards shows your actual Minecraft skin instead of a generic icon.

Dashboard Security#

• /apikey create now prints the generated token as a click-to-copy chat component instead of plain text.
• The external dashboard's paired auth token (the Bearer token it presents on its outbound account-sync webhook) is now encrypted at rest in config.json (AES-256-GCM) instead of stored in plaintext — existing plaintext values are migrated transparently the next time they're read, no action needed.
• New opt-in setting, webDashboard.roleSync (off by default): automatically grants a linked player's dashboard account the ADMIN role the moment they have a configured in-game permission node or belong to a configured permission group, and revokes it again the moment they don't — no more manually re-running /apikey create/the API every time an admin's in-game status changes. Runs an immediate check on join plus a periodic sweep, so it also catches permission changes made outside the mod entirely (e.g. a direct LuckPerms edit). Never touches a role that was set manually — it only ever adjusts a role it granted itself.

Moderation API#

The dashboard's moderation endpoints are backed directly by the same manager classes that power the in-game /ban, /mute, /kick, /warn, /note, and /report commands (see Moderation System) — there is no separate dashboard-only ban store, so actions taken here actually enforce in-game and vice versa. The dashboard's own accounts (dashboard_users, dashboard_registrations) are themselves persisted through the same pluggable backend — see Storage Backend.

All routes above require the standard dashboard Bearer-token authentication (session or API key); mutating routes (POST/DELETE) additionally require the ADMIN role specifically — a MODERATOR-role credential can read but not act.

Public Moderation Lookup (no login required)#

A separate, unauthenticated set of routes — matching ban-management plugins' public transparency page, where anyone can look up a player's punishment history without an account:

These deliberately never expose IP bans, IP mutes, staff notes, or player reports (privacy — notes/reports contain staff commentary and a reporter's identity). Still CORS/rate-limited the same as every other dashboard route, just without the Bearer-token check. Gated by webDashboard.securitySettings.publicModerationLookupEnabled (default true) — set to false to disable public lookup entirely.

In-Chat "View Profile" Link#

Player names in chat show a small clickable ↗ icon that opens that player's public lookup page in a browser. By default this points at whichever NeoEssentials dashboard is actually reachable — the paired external (Laravel) dashboard if you've run /dashboard pair, else the mod's own bundled UI via webDashboard.publicUrl.

If you have your own website instead (a stats page, forum profile, custom fan site), set webDashboard.customProfileUrlTemplate to point the link there instead — it takes priority over both of the above when set:

"customProfileUrlTemplate": "https://myserver.com/players/{player}"

Supports {player} (URL-encoded username) and {uuid} placeholders. Leave empty (the default) to keep using one of the two dashboards.

Commands#

All /dashboard subcommands (including the bare /dashboard) require neoessentials.admin.dashboard — this is checked on the dashboard literal itself, so pair/unpair need it in addition to neoessentials.dashboard.pair listed below (brigadier requires every node from the root down to pass, not just the leaf). Account registration is a separate command tree, /dashboardregister, gated by neoessentials.dashboard.access.

/apikey is a separate command tree from /dashboard//dashboardregister — see API System → Authentication for the full picture of what these keys are for and how they differ from a human dashboard account. /linkaccount is the reverse direction of /dashboardregister — it links an MC account to an existing dashboard account (started from the dashboard's own Settings page), rather than creating a brand-new dashboard account starting from an in-game player.

Permissions#

Unlike most permission nodes documented on the Permission System page, the dashboard nodes above (other than neoessentials.dashboard.apikeys/.pair, which are registered) are not pre-registered in PermissionRegistry — they're checked ad hoc, so grant them explicitly to non-OP groups rather than relying on a documented default.

As of build.16, /help <command> shows each command's real permission node (this table included) instead of guessing neoessentials.<commandname> — that guess used to be wrong for /apikey specifically (it showed neoessentials.apikey instead of the real neoessentials.dashboard.apikeys), and for roughly 160 other commands mod-wide.

Back to Wiki Home