JuByteNexus – Core-API-Referenz

Vollständige Referenz der Core-Plattform-Endpunkte (ohne Module – die sind im Modul-Katalog). Konventionen (Auth, Fehlerobjekt, Pagination) siehe API-Vertrag. Basis: /api/v1.

Endpunkte ohne Permission-Spalte sind öffentlich oder nur authentifiziert; @RequiresPermission-Keys sind angegeben. Aktionen unter 4-Augen-Governance antworten ggf. mit {status:"pending_approval", approvalId}.

Auth & Konto

Auth (`/api/v1/auth`)

Methode	Pfad	Perm	Zweck
POST	`/auth/login`	–	Login (Email/Passwort, optional TOTP)
POST	`/auth/refresh`	–	Access-Token erneuern (Refresh-Rotation)
POST	`/auth/logout`	–	Refresh-Token widerrufen
GET	`/auth/me`	–	Aktueller Benutzer
POST	`/auth/totp/setup` · `/auth/totp/confirm`	–	2FA einrichten/bestätigen

OAuth & WebAuthn (`/api/v1/auth/oauth`, `/api/v1/auth/webauthn`)

Methode	Pfad	Zweck
GET	`/auth/oauth/providers` · `/auth/oauth/discord/url`	OAuth-Provider / Discord-Login-URL
POST	`/auth/oauth/discord/callback`	Discord-Callback → Tokens
POST	`/auth/webauthn/{register\|login}/options` · `/auth/webauthn/{register\|login}`	Passkey-Zeremonien
GET/DELETE	`/auth/webauthn/credentials[/{id}]`	Eigene Passkeys auflisten/entfernen

Account (`/api/v1/account`)

Methode	Pfad	Zweck
PUT	`/account/profile` · `/account/email` · `/account/password`	Profil/Email/Passwort ändern
POST	`/account/logout-all`	Von allen Geräten abmelden
GET/DELETE	`/account/sessions[/{id}]`	Sitzungen auflisten/beenden
GET/POST	`/account/2fa/recovery`	Recovery-Codes zählen/neu generieren

Team, Rechte & Sicherheit

Team & Rollen (`/api/v1`)

Methode	Pfad	Perm	Zweck
GET	`/permissions` · `/roles`	–	Berechtigungen / Rollen auflisten
POST/PUT/DELETE	`/roles[/{id}]`	`core.team.manage`	Rolle anlegen/ändern/löschen
GET	`/team` · `/team/directory`	`core.team.manage` / –	Team-Liste / Email↔MC-Verzeichnis
PUT	`/team/{id}/roles`	`core.team.manage`	Rollen eines Mitglieds setzen
POST	`/team/{id}/disable` · `/team/{id}/enable` · `/team/invite`	`core.team.manage`	Konto sperren/entsperren/einladen
GET	`/team/activity/{leaderboard\|feed}` · `/team/activity/me`	`core.team.manage` / –	Moderations-Leaderboard, Aktivitäts-Feed, eigene Stats

Account-Sicherheit & API-Keys

Methode	Pfad	Perm	Zweck
GET	`/security/accounts`	`core.team.manage`	Suspendierte/gesperrte Konten
POST	`/security/accounts/{id}/unlock`	`core.team.manage`	Locked-out-Konto entsperren
GET/POST/DELETE	`/apikeys[/{id}]`	`core.apikey.manage`	Scoped API-Keys (`nxa_`) verwalten

Server, Nodes & Dateien

Server (`/api/v1/servers`)

Methode	Pfad	Perm	Zweck
GET	`/servers` · `/servers/{id}` · `/servers/{id}/history` · `/servers/{id}/players`	`core.server.view`	Liste/Details/Metrik-Historie/Online-Spieler
DELETE	`/servers/{id}`	`core.server.delete`	Server löschen (optional Datei-Purge)
POST	`/servers/tokens`	`core.server.manage`	Bridge-Token ausstellen
POST	`/servers/{id}/{tags\|group\|broadcast}`	`core.server.manage`	Tags/Gruppe/Broadcast
POST/GET	`/servers/{id}/console[/attach]`	`core.server.console`	Befehl ausführen / Output streamen/puffern
POST	`/servers/{id}/power`	`core.server.lifecycle`	start/stop/restart/kill
POST	`/servers/provision`	`core.server.install`	Server auf Node provisionieren

Dateien, Backups, Welten

Methode	Pfad	Perm	Zweck
GET/PUT/DELETE/POST	`/servers/{id}/files…`	`core.server.files`	Auflisten, lesen/schreiben, verschieben, up/download, (un)archivieren
GET/POST/DELETE	`/servers/{id}/backups…`	`core.server.backup`	Backups (voll/Welt) erstellen/wiederherstellen/löschen
GET/PUT	`/servers/{id}/backup-schedule`	`core.server.backup`	Auto-Backup-Zeitplan
GET/DELETE	`/servers/{id}/worlds[/{name}]`	`core.server.worlds`	Welten auflisten/löschen

Nodes (`/api/v1/nodes`)

Methode	Pfad	Perm	Zweck
GET/PUT/DELETE	`/nodes[/{id}]`	`core.node.manage`	Host-Nodes auflisten/umbenennen/löschen
POST	`/nodes/tokens`	`core.node.manage`	Agent-Token ausstellen

Spieler

Players (`/api/v1/players`)

Methode	Pfad	Perm	Zweck
GET	`/players` · `/players/{id}` · `/players/overview` · `/players/ranks`	`core.player.view`	Suche, Akte, Statistik, Ränge
POST	`/players/{id}/kick` · `/players/{id}/message`	`core.player.kick` / `.message`	Kicken / Nachricht senden
POST	`/players/{id}/rank`	`playermanagement.rank.set`	Rang setzen (netzweit)
GET	`/players/{id}/ips` · `/players/{id}/alts`	`playermanagement.ip.view`	IP-Historie / Alt-Erkennung
POST/DELETE	`/players/{id}/notes[/{noteId}]`	`playermanagement.notes.write`	Notizen
POST/DELETE	`/players/{id}/watch`	`core.player.watch`	Beobachtungsliste
GET	`/public/players/{name}`	–	Öffentliches Profil (wenn aktiviert)

Economy & Security-Alerts

Methode	Pfad	Perm	Zweck
GET	`/players/{id}/economy[/transactions]`	`playermanagement.economy.view`	Balance / Ledger
POST	`/players/{id}/economy/adjust`	`playermanagement.economy.manage`	Balance anpassen
GET	`/security/alerts[/stats]`	`playermanagement.security.view`	Anomalie-Alerts
POST	`/security/alerts/{id}/{resolve\|ignore\|false-positive}`	`playermanagement.security.manage`	Alert bearbeiten

Module, Lizenz & System

Module (`/api/v1/modules`)

Methode	Pfad	Perm	Zweck
GET	`/modules`	–	Module + Status auflisten
POST	`/modules/{id}/enable` · `/modules/{id}/disable`	`core.module.manage`	Aktivieren/Deaktivieren
GET/PUT	`/modules/{id}/config`	`core.module.manage`	Modul-Konfiguration je Scope
GET/POST	`/modules/{id}/config/history[/{changeId}/revert]`	`core.module.manage`	Änderungshistorie / Revert
GET	`/modules/config/all`	`core.module.manage`	Durchsuchbares Settings-Center

Lizenz (`/api/v1/license`)

Siehe Lizenz-API. Kurz: GET /license (öffentlich), GET /license/settings, POST /license/{activate\|activate-key\|refresh}, DELETE /license/key (alle core.license.manage).

System & Plattform

Methode	Pfad	Perm	Zweck
GET	`/system/info` · `/system/health`	`core.module.manage`	Version/Module · Health (DB, Module, Bridges, Agents)
GET	`/asyncapi`	–	AsyncAPI 3.0 (WS-/Webhook-Events)
GET	`/search`	–	Globale Suche (Player, Bans, Tickets, …)
GET/PUT/DELETE	`/feature-flags[/effective]`	`core.flags.manage`	Feature-Flags
GET/PUT/DELETE	`/messages[/{key}]`	`core.messages.manage`	Nachrichten-Katalog
GET/PUT	`/branding` · `…/asset/{kind}`	`core.branding.manage`	Branding (+ öffentlich: `/public/branding…`)
GET/PUT/POST	`/privacy/retention[/run]`	`core.privacy.manage`	GDPR-Aufbewahrung + On-Demand-Purge
GET/POST/PUT/DELETE	`/webhooks[/{id}][/test]`	`core.webhook.manage`	Outbound-Webhooks
GET	`/audit[/verify\|/export]`	`core.audit.view`	Audit-Log (Hash-Chain, CSV)
GET/POST	`/approvals…`	`core.approval.{view\|request\|decide}`	4-Augen-Genehmigungen
GET/POST/PUT/DELETE	`/policies…`	`core.policy.manage`	Governance-Policies
GET/POST	`/setup[/status]`	–	First-Run-Wizard (Owner anlegen)

UCP (User Control Panel, `/api/v1/ucp`)

Methode	Pfad	Zweck
POST	`/ucp/register` · `/ucp/link`	Account registrieren / Identität verknüpfen
GET/PUT	`/ucp/me/identities` · `/ucp/me/public-profile`	Identitäten / öffentliches Profil
GET/POST	`/ucp/me/punishments[/{id}/appeal]`	Eigene Strafen / Einspruch
GET/DELETE	`/ucp/me/data-export` · `/ucp/me`	GDPR-Export / Account-Löschung

Realtime (WebSocket)

Pfad	Zweck
`/api/v1/ws`	Panel-Realtime: Client `subscribe` auf `player.`, `ban.`, `server.`, `module.`, `report.*`, `notification.created`; Server pusht `{type,data,at}`
`/bridge/ws`	Bridge↔Core: Handshake (Token→Server-Key), Player-Events, Vault-Sync, Metrik-Heartbeat, Straf-/Console-Requests (Bridge-Protokoll)
`/agent/ws`	Host-Agent↔Core: Node-Heartbeat, Server-State, Console-Output

Event-Bus (Auswahl der Core-Events)

player.join · player.quit · player.chat · player.report · player.device · player.inventory · chatlog.requested · server.online · server.offline · punishment.request · punishment.revoke · scheduler.run.result · vault.groups · notification.created · module.enabled · module.disabled · config.changed

Module abonnieren diese per @Subscribe und publizieren eigene Events – siehe Modul-Katalog und SDK-Referenz.

JuByteNexus – Core-API-Referenz

Auth & Konto

Auth (/api/v1/auth)

OAuth & WebAuthn (/api/v1/auth/oauth, /api/v1/auth/webauthn)

Account (/api/v1/account)