OAuth2

Lass Menschen sich mit ihrem Zrzur-Konto auf deiner Website anmelden. Das Installieren eines Bots nutzt denselben Bildschirm.

Das brauchst du

Eine Anwendung und eine Website oder ein Programm, das eine Weiterleitung empfangen kann.

Was es kann und was nicht

Ein Zugriffstoken liest, wer jemand ist und auf welchen Servern. Es funktioniert nur auf /oauth2/@me.... Es handelt nie als die Person auf dem Rest der API.

Scope	Gibt
`identify`	`GET /oauth2/@me`
`servers.read`	`GET /oauth2/@me/servers`
`applications.commands`	Markiert, dass deine Befehle dazukommen dürfen
`bot.install`	Installiert den Bot auf einem Server, den die Person wählt

Schritte

Öffne deine Anwendung, Tab OAuth2. Trage deine Weiterleitungs-URIs ein, eine pro Zeile, bis zu 10: https://-Adressen oder http://localhost beim Entwickeln. Sie müssen exakt passen.
Erzeuge ein Client-Geheimnis, wenn dein Programm auf einem Server läuft. Ohne eins ist die App ein öffentlicher Client. Es erscheint einmal.
Erzeuge für jede Anmeldung ein zufälliges state und einen zufälligen code_verifier. Schicke die Person zu:

/oauth2/authorize
  ?client_id=YOUR_BOT_ID
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &response_type=code
  &scope=identify%20servers.read
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_OF_SHA256_OF_VERIFIER
  &code_challenge_method=S256

Dieser Pfad liegt in der Zrzur-App. Der URL-Generator im Tab OAuth2 baut diese Adresse. PKCE (code_challenge) ist immer Pflicht, auch mit Client-Geheimnis.

Die Person stimmt zu. Der Browser kommt mit code und state zu deiner Weiterleitungs-URI zurück. Prüfe, dass state deins ist.
Tausche den Code innerhalb von 10 Minuten ein. Er funktioniert einmal.

curl -X POST "https://api.zrzur.com/oauth2/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_BOT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d redirect_uri=https://example.com/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "identify servers.read"
}

Rufe die API damit auf:

curl "https://api.zrzur.com/oauth2/@me" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Die PKCE-Werte erzeugen

code_verifier ist ein zufälliger Text mit 43 bis 128 Zeichen. code_challenge ist das SHA-256 dieses Texts, als base64url ohne Auffüllung kodiert. Behalte den Verifier bis Schritt 5 und sende nur die Challenge in der Adresse.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");

Aktualisieren und widerrufen

Zugriffstokens halten 1 Stunde, Aktualisierungstokens 30 Tage. Jedes Aktualisierungstoken geht einmal und kommt neu zurück. Ein altes zu nutzen beendet die ganze Kette, denn das sieht nach Diebstahl aus.

curl -X POST "https://api.zrzur.com/oauth2/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_BOT_ID \
  -d refresh_token=YOUR_REFRESH_TOKEN

curl -X POST "https://api.zrzur.com/oauth2/revoke" \
  -d client_id=YOUR_BOT_ID \
  -d token=YOUR_REFRESH_TOKEN

Beide Routen nehmen ein Formular, kein JSON. Sie stehen nicht im OpenAPI-Dokument. Eine Person kann deine App auch in ihren Einstellungen entziehen.

Häufige Fehler

Diese Routen antworten { "error": "...", "error_description": "..." }.

`error`	Ursache	Lösung
`invalid_request`	Ein Feld fehlt, etwa `code_verifier`	Sende jedes Feld
`invalid_grant`	Der Code ist unbekannt, benutzt oder abgelaufen, oder PKCE ist falsch	Beginne die Anmeldung neu
`invalid_client`	Client-ID oder Geheimnis sind falsch (Status `401`)	Prüfe sie
`invalid_scope`	Mehr Scope als bei der ersten Zustimmung	Fordere weniger an
`unsupported_grant_type`	Ein anderer Grant-Typ	Nimm die beiden oben