Autorisierung

Chess Scanner nutzt den standardmäßigen OAuth-2.0-Authorization-Code-Flow mit PKCE, und PKCE ist für jeden Client verpflichtend. Du durchläufst diesen Flow einmal pro Nutzer, um ein Access-Token zu bekommen, und rufst damit die API auf.

Diese Endpunkte liegen auf dem OAuth-Provider:

Schritt	Endpunkt
Autorisieren (Browser-Weiterleitung)	`GET https://chessscanner.com/api/auth/oauth2/authorize`
Token-Tausch (serverseitig)	`POST https://chessscanner.com/api/auth/oauth2/token`

1. PKCE-Paar erzeugen

Erzeuge einen zufälligen code_verifier und leite daraus einen code_challenge ab:

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

const codeVerifier = randomBytes(48).toString("base64url");
const codeChallenge = createHash("sha256")
  .update(codeVerifier)
  .digest()
  .toString("base64url");

Behalte den code_verifier für Schritt 3, zum Beispiel in einem kurzlebigen, httpOnly-Cookie. Erzeuge außerdem einen zufälligen state-Wert als CSRF-Schutz.

2. Nutzer zur Autorisierung weiterleiten

Schicke den Browser des Nutzers zum Authorize-Endpunkt:

https://chessscanner.com/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=DEINE_CLIENT_ID
  &redirect_uri=https://deine-app.de/oauth/callback
  &scope=user.read databases.read games.read offline_access
  &state=ZUFALLS_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Der Nutzer meldet sich bei Bedarf an, bestätigt die Zustimmungsseite und kommt zu deiner redirect_uri mit code und state zurück:

https://deine-app.de/oauth/callback?code=AUTH_CODE&state=ZUFALLS_STATE

Mit &prompt=consent zeigst du die Zustimmungsseite jedes Mal an. Das ist beim Testen praktisch, da ein bereits autorisierter Nutzer sonst direkt zurückgeleitet wird.

3. Code gegen ein Token tauschen

Prüfe auf deinem Server, dass state mit dem gesendeten Wert übereinstimmt, und sende dann eine application/x-www-form-urlencoded-POST-Anfrage an den Token-Endpunkt:

curl -X POST https://chessscanner.com/api/auth/oauth2/token \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://deine-app.de/oauth/callback \
  -d client_id=DEINE_CLIENT_ID \
  -d client_secret=DEIN_CLIENT_SECRET \
  -d code_verifier=DEIN_CODE_VERIFIER

Antwort:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "user.read databases.read games.read"
}

4. Das Token verwenden

Rufe die API mit dem Access-Token auf:

curl https://api.chessscanner.com/api/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Alle Endpunkte findest du in der API-Referenz.

Refresh-Tokens (dauerhafter Zugriff)

Fordere den Scope offline_access an (wie im Beispiel oben), dann bekommst du zusätzlich zum Access-Token ein Refresh-Token:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "user.read databases.read games.read offline_access"
}

Bewahre das Refresh-Token sicher auf. Wenn das Access-Token abläuft, tausche das Refresh-Token gegen ein neues, ganz ohne Nutzerinteraktion:

curl -X POST https://chessscanner.com/api/auth/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=DEIN_REFRESH_TOKEN \
  -d client_id=DEINE_CLIENT_ID \
  -d client_secret=DEIN_CLIENT_SECRET

So kann ein Backend die Partien eines Nutzers dauerhaft abrufen. Kommt in der Antwort ein neues refresh_token, ersetze das gespeicherte.

Ohne offline_access bekommst du kein Refresh-Token und musst den Flow erneut durchlaufen, sobald das Access-Token abläuft. Refresh-Tokens werden ungültig, wenn der Nutzer oder der App-Besitzer die Tokens der App widerruft.

Gut zu wissen

Der Token-Endpunkt nutzt client_secret_post, sende also client_id und client_secret im Body (wie oben).
Die angefragten Scopes müssen eine Teilmenge der deiner App gewährten Scopes sein, sonst erhältst du invalid_scope.
Tokens sind opak, also keine JWTs. Validiere sie über einen API-Aufruf statt durch Dekodieren.

ChessScanner