OAuth2-Anmeldung

Eine Discord-ähnliche Anmeldung umstellen

Registriere eine Hosting-Anwendung. Tausche dann Authorization-, Token- und Benutzer-Endpunkt sowie Client-ID und Secret gegen die Hosting-Zugangsdaten aus. Discord-Zugangsdaten funktionieren hier nicht. Hinterlege dieselbe Callback-URL im Entwicklerportal. Der identify/email-Code-Flow und die Benutzerantwort folgen Discord-Konventionen; Bot-, Guild- und andere Discord-APIs werden nicht nachgebildet. IDs gehören zu Hosting-Konten, nicht zu Discord-Konten.

Endpunkte

GET

https://hosting.marvinmc.net/oauth2/authorize

POST

https://hosting.marvinmc.net/api/oauth2/token

GET

https://hosting.marvinmc.net/api/users/@me

POST

https://hosting.marvinmc.net/api/oauth2/token/revoke

Die API-Endpunkte akzeptieren auch /api/v6 bis /api/v10, zum Beispiel /api/v10/users/@me. /oauth/authorize, /oauth/token, /oauth/userinfo und /oauth/revoke bleiben verfügbar. Die bisherige userinfo-Antwort behält sub und email_verified.

Berechtigungen

identify

Dein Konto anhand von Benutzer-ID und Benutzername erkennen.

email

Deine E-Mail-Adresse und ihren Bestätigungsstatus lesen.

connections.read

ID und Benutzername deines verknüpften Discord-Kontos lesen. Keine Discord-Tokens werden weitergegeben.

customer.read

Lesen, ob dein Konto als zahlender Kunde gilt. Keine Beträge oder Zahlungen werden weitergegeben.

server.read

Den ausgewählten Server, seine Ressourcen und Live-Statistiken lesen.

server.start

Den ausgewählten Server starten.

server.stop

Den ausgewählten Server stoppen.

server.restart

Den ausgewählten Server neu starten.

identify ist erforderlich und wird verwendet, wenn scope fehlt. Ergänze email nur bei Bedarf. Der bisherige Scope profile bleibt als Alias für identify verfügbar.

Serverfreigaben und Hosting-API

Aktiviere die benötigten Scopes im Entwicklerportal und übergib sie in scope, zum Beispiel identify server.read server.restart. Der Inhaber wählt auf der Freigabeseite ausdrücklich einen geeigneten Server aus. Jedes Token und seine Refresh-Tokens bleiben an diese Installation gebunden. Für einen weiteren Server erneut autorisieren und dessen Tokens separat speichern. Server-Scopes erfordern immer eine sichtbare Zustimmung; prompt=none liefert consent_required.

Bei Server-Scopes enthält die Token-Antwort zusätzlich server_id, die bei der Zustimmung ausdrücklich ausgewählte Server-ID. Speichere sie zusammen mit diesem Token. Refresh behält diese Bindung bei. Reine Identitätsantworten bleiben unverändert.

Bearer-Tokens funktionieren an den unten aufgeführten Kunden-API-Endpunkten. Der Servertyp muss API-Zugriff erlauben. Captcha-Pflichten können nicht umgangen werden. Unter Server > Berechtigungen können Inhaber einzelne Aktionen abschalten oder die App entfernen. Eine neue Autorisierung reaktiviert keine Tokens einer entfernten Installation. Ein kontoweiter Widerruf entfernt auch alle Serverinstallationen. Passwortwechsel, App-Änderungen und Secret-Wechsel machen Tokens ungültig. Diese Scopes erlauben keine Käufe, Dateizugriffe, Konsolenbefehle oder das Beenden von Prozessen.

GET /api/client/v1/connections

connections.read

GET /api/client/v1/customer

customer.read

GET /api/client/v1/servers

server.read

GET /api/client/v1/servers/{id}

server.read

GET /api/client/v1/servers/{id}/stats

server.read

POST /api/client/v1/servers/{id}/power

server.start | server.stop | server.restart

GET /api/client/v1/jobs/{id}

Dieselbe App, Serverinstallation und Aktionsberechtigung

curl https://hosting.marvinmc.net/api/client/v1/servers/SERVER_ID/power \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: UNIQUE_REQUEST_ID' \
  --data '{"action":"restart"}'

Power-Anfragen liefern HTTP 202 mit einem Auftrag; frage dessen API-Endpunkt mit einem gültigen Token derselben App und Serverinstallation mit dem Aktionsrecht ab. Vor Ausführung werden das ursprüngliche Token und die aktuellen Rechte erneut geprüft. Abgelaufene oder widerrufene Tokens können keine Aufträge ausführen. GET servers liefert nur den ausgewählten freigegebenen Server; stats liefert Live-Status und Auslastung. connections enthält nur die öffentliche Discord-Identität; customer liefert paid_customer als Boolean. Fehler: 401 ungültiges Token, 403 fehlende Rechte, 409 beschäftigt, 429 Anfragelimit (60 Anfragen pro Minute je App und Nutzer). Retry-After beachten. Antworten dürfen nicht gecacht werden.

1. Anwendung registrieren

Erstelle eine Anwendung im Entwicklerportal. Unter Allgemeine Informationen kannst du Name, Logo, Beschreibung und öffentliche Links ergänzen. Hinterlege unter OAuth2 die exakte Callback-URL und aktiviere den E-Mail-Zugriff nur bei Bedarf. Das Client-Secret gehört ausschließlich ins Backend, niemals in Browser- oder Mobilgerätecode. Falls es verloren geht, wähle unter OAuth2 Secret neu generieren: Anwendung und Client-ID bleiben erhalten, das neue Secret wird einmalig angezeigt. Ersetze das alte Secret in deiner Integration; bisherige Codes und Tokens werden ungültig. Native Anwendungen verwenden den öffentlichen Typ ohne Secret. Der URL-Generator kann eine PKCE-Testanfrage vorbereiten.

2. Nutzer weiterleiten

Leite mit response_type=code, client_id, registrierter redirect_uri und scope=identify email zum Authorization-Endpunkt weiter. State ist optional und wird unverändert zurückgegeben, falls mitgesendet (maximal 2048 Bytes, keine Steuerzeichen). Ein frischer zufälliger State, gebunden an die Anwendungssitzung, wird zum CSRF-Schutz dringend empfohlen. PKCE S256 ist für Backends mit Client-Secret optional, für öffentliche Clients Pflicht. Das Beispiel verwendet beide Schutzmaßnahmen: State und Verifier in der Sitzung speichern; der Verifier hat 43–128 Zeichen, die Challenge ist base64url(SHA-256(verifier)) ohne Padding.

$state = bin2hex(random_bytes(32));
$verifier = rtrim(strtr(base64_encode(random_bytes(32)), '+/', '-_'), '=');
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
$_SESSION['marvinmc_oauth'] = ['state' => $state, 'verifier' => $verifier];
$url = 'https://hosting.marvinmc.net/oauth2/authorize?' . http_build_query([
    'response_type' => 'code',
    'client_id' => 'YOUR_CLIENT_ID',
    'redirect_uri' => 'https://example.com/auth/marvinmc/callback',
    'scope' => 'identify email',
    'state' => $state,
    'code_challenge' => $challenge,
    'code_challenge_method' => 'S256',
], '', '&', PHP_QUERY_RFC3986);
header('Location: ' . $url);
exit;

3. Callback prüfen

Wenn du state gesendet hast, vergleiche den Rückgabewert in konstanter Zeit mit deiner Sitzung und lehne fehlende oder abweichende Werte ab. Prüfe den zurückgegebenen Aussteller iss gegen https://hosting.marvinmc.net. Auch ohne state muss deine Integration ihren Callback gegen CSRF schützen; das Hosting-Freigabeformular ersetzt diesen Schutz nicht. Behandle error=access_denied ohne Anmeldung. Tausche den Code einmal innerhalb von 5 Minuten mit exakt der ursprünglichen redirect_uri ein. Sende code_verifier nur, wenn eine Challenge verwendet wurde.

4. Code eintauschen

Sende application/x-www-form-urlencoded per POST, kein JSON. Backend-Clients authentifizieren sich per HTTP Basic (ID und Secret vor Base64 jeweils URL-kodieren) oder mit client_id und client_secret im Body, niemals beides. Öffentliche Clients senden client_id ohne Secret. Ohne PKCE-Challenge wird code_verifier weggelassen. Die Antwort enthält access_token, token_type=Bearer, expires_in, refresh_token und scope. Zugriffstokens gelten derzeit 900 Sekunden; verwende expires_in und nicht fest angenommene Discord-Laufzeiten.

curl https://hosting.marvinmc.net/api/oauth2/token \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'code=CALLBACK_CODE' \
  --data-urlencode 'redirect_uri=https://example.com/auth/marvinmc/callback' \
  --data-urlencode 'code_verifier=SESSION_VERIFIER'

5. Benutzerprofil abfragen

Rufe /api/users/@me mit Authorization: Bearer auf. Verwende id als stabilen Hosting-Kontoschlüssel. identify liefert id, username, discriminator="0", global_name und avatar=null. email und verified erscheinen nur mit dem Scope email. Die verknüpfte Discord-Identität ist separat mit connections.read verfügbar. Hosting-Aktionen erfordern eigene Scopes und eine ausdrückliche Serverfreigabe; Guthaben auszugeben wird nicht unterstützt.

curl https://hosting.marvinmc.net/api/users/@me \
  -H 'Authorization: Bearer ACCESS_TOKEN'

{
  "id": "123456789012345678",
  "username": "example",
  "discriminator": "0",
  "global_name": "example",
  "avatar": null,
  "email": "example@example.com",
  "verified": true
}

6. Tokens erneuern

Sende grant_type=refresh_token, refresh_token und dieselbe Client-Authentifizierung an den Token-Endpunkt. Jede Erneuerung liefert neue Zugriffs- und Refresh-Tokens; speichere beide zusammen. Die vorherigen Tokens werden ungültig. Refresh-Tokens laufen 30 Tage nach ihrer Ausstellung ab. Erneuere dasselbe Token niemals parallel: Die Wiederverwendung eines alten Refresh-Tokens widerruft seine Token-Familie und erfordert eine neue Anmeldung. Ein optionaler scope darf Berechtigungen reduzieren, aber nicht erweitern. Ein PKCE-Verifier ist beim Erneuern nicht erforderlich.

curl https://hosting.marvinmc.net/api/oauth2/token \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'refresh_token=REFRESH_TOKEN'

Widerruf und Fehler

Sende token (Zugriffs- oder Refresh-Token) und Client-Authentifizierung per POST an /api/oauth2/token/revoke. Dies widerruft die Nutzerfreigabe für diese Anwendung samt Codes, Zugriffs- und Refresh-Tokens. Unbekannte oder bereits widerrufene Tokens liefern ebenfalls HTTP 200. Passwortwechsel, erzwungene Passwortwechsel, Änderungen, Pausieren und Secret-Austausch machen betroffene Tokens ungültig. Die Wiederverwendung eines Codes widerruft seine Token-Familie. Behandle invalid_request, invalid_client, invalid_grant, invalid_scope, invalid_token und HTTP 429; beachte Retry-After.

curl https://hosting.marvinmc.net/api/oauth2/token/revoke \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'token=ACCESS_OR_REFRESH_TOKEN'

Protokoll und Grenzen

Nur OAuth2: kein OpenID Connect, ID-Token, Passwort-, Implicit- oder Client-Credentials-Grant. Token-, Profil- und Widerruf-Anfragen erfolgen über Backend oder nativen Client; Browser-CORS ist nicht freigeschaltet. Callbacks müssen exakt übereinstimmen. PKCE muss, wenn verwendet, S256 sein; öffentliche Clients dürfen es nicht weglassen. Normale Anfragen und prompt=consent zeigen die Freigabe. prompt=none funktioniert nur bei einem angemeldeten, bestätigten Nutzer mit unveränderter, zuvor freigegebener Anwendung und Berechtigungen; sonst erhält der Callback login_required oder consent_required. Die normale Passkey-/2FA-Absicherung bleibt bestehen.