Reauth + Token-Erneuerung

Nach einer erfolgreichen Twitch-Verbindung bekommst du einen Access-Token (kurzlebig) und einen Refresh-Token (langlebig). Chatlix erneuert den Access-Token automatisch im Hintergrund, sobald er bald abläuft. Solange das funktioniert, musst du nichts tun.

Manchmal funktioniert es nicht. Diese Seite erklärt, wann und warum, und wie du es behebst.

Wann genau wird erneuert

Chatlix prüft bei jeder Twitch-API-Operation, ob der gespeicherte Access-Token noch mindestens 60 Sekunden gültig ist (token_expires_at <= now() + 60s löst die Erneuerung aus). Das ist knapper getaktet, als man vermuten würde — es reicht also nicht, „irgendwann in den nächsten Minuten“ zu erneuern, sondern es passiert sehr kurz vor Ablauf, praktisch on-demand beim nächsten API-Call.

Weil mehrere Chatlix-Worker gleichzeitig auf denselben Twitch-Account zugreifen können (z. B. Follow-Sync, Follow-Age-Berechnung, EventSub-Fanout, VOD-Import), gibt es einen eigens gebauten Schutz gegen Refresh-Races: Bevor ein Worker refresht, versucht er einen Redis-Lock (lock:twitch_refresh:<account-id>, 10 Sekunden TTL, per SETNX) zu setzen. Bekommt ein zweiter Worker den Lock nicht, wartet er 500ms und liest danach die bereits erneuerten Token aus der Datenbank neu, statt selbst einen zweiten Refresh anzustoßen. Das ist wichtig, weil Twitch den Refresh-Token bei jedem Refresh-Aufruf rotiert — ein zweiter, gleichzeitiger Refresh-Versuch mit dem alten Token würde sonst scheitern und den Account in einen kaputten Zustand bringen.

Wenn die Erneuerung fehlschlägt

Anders als früher an dieser Stelle beschrieben, gibt es keinen Fehlercode TWITCH_TOKEN_EXPIRED im Code. Tatsächlich passiert Folgendes: Schlägt der Refresh-Call fehl, gibt die zuständige Funktion intern null zurück und schreibt einen Log-Eintrag twitch_token_refresh_failed. Neue Token werden vor dem Speichern zusätzlich validiert (u. a. wird eine Antwort mit expires_in <= 60 verworfen) — auch eine scheinbar erfolgreiche, aber unplausible Antwort von Twitch führt also nicht zu einem gespeicherten, kaputten Zustand.

Mögliche Ursachen für einen fehlgeschlagenen Refresh:

Du hast Chatlix bei Twitch entzogen (Twitch-Settings → Connections → „Disconnect“). Der Refresh-Token ist damit ungültig.
Twitch hat den Token invalidiert — zum Beispiel nach einem Passwort-Wechsel oder einem Security-Alert auf deinem Twitch-Account.
Du hast dein Twitch-Passwort geändert — Twitch invalidiert dabei je nach Einstellung alle Drittanbieter-Token.
Twitch-API-Outage während des Refresh-Versuchs. Chatlix versucht es beim nächsten API-Call erneut; meistens behebt sich das selbst.

Was passiert in der Zwischenzeit

Solange der Refresh fehlschlägt:

EventSub-Subscriptions laufen weiter, soweit Twitch sie noch ohne aktiven User-Token akzeptiert. Manche Event-Typen werden aber pausiert oder gehen in den revoked-Status.
API-Aufrufe, die deinen User-Token brauchen (z. B. Chat-Posting, Reward-Management, Moderator-Aktionen), schlagen fehl.
Der zentrale Bot-Account (siehe Twitch verbinden) ist von deinem persönlichen Token-Problem unabhängig — Bot-Chat-Nachrichten laufen über die eigene Schnittstelle /v1/bot/system-credentials und damit über den separat verwalteten Bot-Token. Ist umgekehrt der Bot-Account selbst nicht konfiguriert oder sein Token kaputt, liefert diese Schnittstelle den Fehlercode bot_account_not_configured.
Chatlix zeigt im Dashboard ein Banner „Twitch-Verbindung abgelaufen — bitte neu verbinden“.

Kein Datenverlust: deine Automationen, Regeln, gespeicherten Rewards bleiben unverändert.

Reauth-Flow

Dashboard → Integrations → « Twitch neu verbinden ».

Der Ablauf ist identisch zum erstmaligen Verbinden (siehe Twitch verbinden, Endpoints /oauth/twitch/login und /oauth/twitch/callback). Du wirst zu Twitch geschickt, bestätigst die Berechtigungen (Twitch zeigt dir dabei immer die volle Scope-Liste, siehe Permissions verstehen — meist reicht ein Klick auf „Authorize“), und kommst zurück. Chatlix tauscht den Code gegen frische Token, registriert EventSub-Subscriptions neu, und das Banner verschwindet.

Dauert insgesamt etwa 20 Sekunden.

Wenn Reauth fehlschlägt

„Access denied“ auf Twitch: du hast „Cancel“ geklickt. Nochmal starten.
oauth_state_invalid direkt beim Zurückkommen: der von Chatlix in Redis hinterlegte state-Wert ist abgelaufen oder passt nicht (z. B. weil der Flow in einem anderen Tab/Browser abgeschlossen wurde, oder zu viel Zeit vergangen ist). Im selben Tab zügig neu starten.
„redirect_uri mismatch“: die konfigurierte Redirect-URI weicht von https://chatlix.app/oauth/twitch/callback ab — Custom-Domain-Konfigurationsproblem. Support kontaktieren.
Sofort erneut fehlgeschlagener Refresh nach Reauth: prüfe, ob du kurz zuvor dein Twitch-Passwort geändert hast oder ob Twitch aktuell eine API-Störung meldet. Support kontaktieren, wenn es nach 10 Minuten nicht von selbst läuft.
Stiller Erfolg, aber Events fehlen weiter: Dashboard → Integrations → Twitch → « Diagnose » → « Subscriptions neu registrieren ». Twitch braucht manchmal einen expliziten Re-Subscribe nach Token-Wechsel.
Einzelne Aktion scheitert mit „missing_scope“ trotz erfolgreichem Reauth: seltener Fall, meist bei ganz neuen Features. Support kontaktieren — eventuell muss die Scope-Liste serverseitig aktualisiert werden.

Technischer Hintergrund — wie es intern läuft

Für Interessierte: Access- und Refresh-Token liegen verschlüsselt in der Tabelle twitch_accounts (access_token_ciphertext, refresh_token_ciphertext). Refresh-Calls laufen über https://id.twitch.tv/oauth2/token mit grant_type=refresh_token. Bei Erfolg werden Access- und Refresh-Token rotiert, validiert und verschlüsselt neu gespeichert; der Redis-Lock lock:twitch_refresh:<account-id> verhindert dabei parallele Refresh-Versuche mehrerer Worker. Bei Fehler wird kein spezieller Status-Code in der Datenbank gesetzt, sondern der fehlgeschlagene Versuch geloggt (twitch_token_refresh_failed) und beim nächsten Bedarf erneut versucht.

Relevante Endpoints: OAuth-Start /oauth/twitch/login, Callback /oauth/twitch/callback, EventSub-Inbox /webhook/twitch/eventsub (Legacy) bzw. /v1/twitch/eventsub/webhook (versioniert), Bot-Token-Ausgabe /v1/bot/system-credentials (nur für interne Worker per JWT).

Best Practices

Kein Twitch-Passwort-Wechsel kurz vor einem wichtigen Stream. Wenn du es musst: danach kurz warten, ins Dashboard, Reauth.
Bei „Verbindung trennen“ auf Twitch direkt: sofort danach im Chatlix-Dashboard Reauth durchführen, damit Automationen nicht stillschweigend ausfallen.
Diagnose-Seite im Auge behalten — sie zeigt Subscriptions, ihren Status und das letzte erfolgreich empfangene Event pro Typ.
Bot-Probleme von Account-Problemen unterscheiden: Schreibt der Bot nicht mehr im Chat, aber Reward-Events kommen weiterhin an, liegt das Problem eher am Bot-Account (siehe Twitch verbinden) als an deinem eigenen Token — Reauth deines Accounts hilft in dem Fall nicht.