07 · Häufige Fragen und Fehlerbehebung

Gesamtübersicht der Fehlercodes

`WsaVerificationError.code`, geworfen von `verifyWsa`

code	Häufige Ursache	Wie zu untersuchen
`InvalidSignature`	Falscher Schlüssel, manipuliertes Token, falscher Schlüssel für Tier1/Tier2 verwendet	Sicherstellen, dass der im Backend verwendete Schlüssel mit dem registrierten/verteilten übereinstimmt; per-App-Schlüssel als unveränderte Zeichenkette übergeben, keine Hex-Dekodierung
`WrongAudience`	`audience` stimmt nicht mit dem Token-`aud` überein	`audience` muss exakt gleich dem Host der Registrierungs-URL sein (z. B. `app.example.com`), ohne Port/Protokoll
`WrongIssuer`	`issuer`-Konfiguration wurde geändert	Standard `gptbots-workspace` beibehalten
`Expired`	Token über 5 Minuten alt, Serveruhr abweichend	Serveruhr per NTP synchronisieren; das `wsa` ist ein einmaliges Bootstrap-Token, nicht cachen und später wiederverwenden
`NotYetValid`	`iat`/`nbf` in der Zukunft	In der Regel sind Signatur- und Prüfseite stark unsynchronisiert
`MissingClaim`	Fehlendes `exp`/`sub`/`role`/`workspace_id`	Einem regulären Plattform-Token fehlt nichts; tritt es auf, ist die Herkunft des Tokens verdächtig
`UnsupportedAlgorithm`	`alg` nicht in der Whitelist	Standardmäßig nur `HS256`; RS256 erfordert explizit `algorithms:['RS256']` + `publicKey`
`InvalidToken`	Token leer/strukturell ungültig/abgeschnitten	Prüfen, ob das Frontend das vollständige `wsa` korrekt erhalten hat und ob die URL von einer Zwischenschicht umgeschrieben wurde

`/token`-Austauschphase (Pull)

code	Bedeutung	Auslösebedingung
`403209`	Invalid grant	`code` fehlt, ist abgelaufen oder wurde bereits verwendet (Wiederholung). Der `code` ist nur einmal verwendbar
`403210`	Invalid verifier	PKCE-`codeVerifier` stimmt nicht mit dem `code_challenge` vom Start überein

Push-`sign-token` (wird vom Workspace-Frontend aufgerufen, nur zur Information)

code	Bedeutung	Auslösebedingung
`40000`	Parameter error	URL nicht registriert, `auth_mode` ist nicht `workspace_account`
`40100`	Permission deny	Nicht angemeldet oder Session ungültig
`40105`	Require member of project	Klickende Person ist kein Mitglied dieses Workspace
`40320`	Member not found	Konto abgemeldet/gelöscht

FAQ

F: Soll ich Push oder Pull wählen?
A: Einstieg auf der Workspace-Seite „Erweiterungen", „eingebettete App" gewünscht → Push (am einfachsten). Ist Ihre App eine eigenständige Website und möchten Sie einen „Mit GPTBots anmelden"-Button platzieren → Pull (M-Auth, sicherer, wsa gelangt nicht in den Browser). Siehe 02.

F: Kann ich das JWT direkt im Frontend parsen, um an die Nutzerinformationen zu kommen?
A: Sie können es öffnen und ansehen, aber nicht als vertrauenswürdige Identität behandeln – ohne Schlüssel lässt sich die Signatur nicht prüfen, der Payload kann gefälscht sein. Jede Autorisierungsentscheidung muss sich nach dem Ergebnis von verifyWsa im Backend richten. Siehe 05 §5.

F: Was tun, wenn das wsa abgelaufen ist?
A: Das wsa ist nur ein einmaliges Bootstrap-Token (5 Minuten). Beim Landen einmal prüfen, in Ihre eigene Session umwandeln und danach immer Ihre Session verwenden, nicht mehr auf das wsa stützen. Beim nächsten Öffnen über die Erweiterungsseite erhalten Nutzer:innen ein neues wsa.

F: consumeHandoff auf der Landingpage wirft „no handoff token present"?
A: Das bedeutet, die aktuelle URL enthält kein ?wsa= – möglicherweise hat die Person direkt zugegriffen, oder das wsa wurde bereits durch einen vorherigen erfolgreichen Austausch entfernt. Unterscheiden Sie zwischen „erstmaligem Landen mit Token" und „normalem Zugriff"; Letzteres nimmt Ihren eigenen Anmelde-/Anonym-Zweig.

F: Der Pull-Login-Callback meldet StateMismatch / MissingRequest?
A: MissingRequest = startWorkspaceLogin wurde nicht zuvor in derselben Browsersitzung aufgerufen (der PKCE-verifier liegt im sessionStorage; ein Tab-Wechsel oder das Löschen des Storage lässt ihn verloren gehen). StateMismatch = das Callback-state stimmt nicht mit dem gespeicherten überein (CSRF-Schutz); stellen Sie sicher, dass nicht geräte-/sitzungsübergreifend gearbeitet wird.

F: Der Pull-Login meldet CryptoUnavailable?
A: PKCE benötigt Web Crypto, das nur in einem sicheren Kontext (HTTPS oder localhost) verfügbar ist. Debuggen Sie mit HTTPS oder lokal über localhost.

F: redirect_uri meldet invalid_request / kehrt zur Organisationsauswahlseite zurück?
A: scheme + host der redirect_uri müssen exakt gleich client_id (Registrierungs-URL) sein. Eine https-App darf keinen http-Callback konfigurieren; der host muss übereinstimmen. Die Plattform springt niemals zu einer ungeprüften Adresse, daher kehrt sie zur Organisationsauswahlseite mit ?error=invalid_request zurück.

F: Wie verwende ich den per-App-Schlüssel als HMAC-Key? Ist eine base64/hex-Dekodierung nötig?
A: Als unveränderte Zeichenkette übergeben (SDK und Plattform verwenden beide die UTF-8-Bytes direkt als HMAC-Key). Der Tier-2-Schlüssel hat die Form wext_+64 hex; die gesamte Zeichenkette ist der Schlüssel, nicht erneut dekodieren.

F: Kann ich das SDK in einem CommonJS-Projekt verwenden?
A: Das SDK ist ESM. Verwenden Sie in einem CJS-Projekt ein dynamisches import() oder wandeln Sie die betreffenden Module in ESM um.

F: Wie ändere ich Symbol/Name?
A: Tier 2 in der Space-Verwaltung bearbeiten; für Tier 1 den Plattform-Betrieb kontaktieren, um den Verzeichniseintrag zu ändern.

F: Was passiert, wenn der Administrator meine App deaktiviert?
A: Der Organisationsadministrator kann eine App in der Space-Verwaltung deaktivieren (einschließlich der Sichtbarkeit öffentlicher Plattform-Apps in dieser Organisation). Nach der Deaktivierung sehen die Mitglieder dieser Organisation auf der Erweiterungsseite keinen Einstieg mehr, und die Plattform signiert für diese Organisation kein wsa mehr (sowohl Push als auch Pull werden abgelehnt).

Debugging-Checkliste

audience == host der Registrierungs-URL (häufigste Ursache für WrongAudience)
Backend-Schlüssel stimmt mit dem registrierten/verteilten überein und liegt nur im Backend
Serveruhr per NTP synchronisiert (Expired / NotYetValid liegen oft an der Uhr)
Nach dem Landen mit history.replaceState das wsa / code entfernt
In eigene Session umgewandelt, nachfolgende Anfragen reichen kein wsa weiter
Pull: sicherer Kontext HTTPS/localhost; redirect_uri hat dieselbe Domain wie client_id
Mandantentrennung anhand von workspace_id

Referenzen

Die Artikel dieses Leitfadens: 01 Schnellstart · 02 Kernkonzepte · 03 Push · 04 Pull · 05 Prüfung und Sicherheit · 06 API