Kernkonzepte

Dieser Leitfaden hilft Entwickler:innen zu verstehen: zu welcher Erweiterungsschicht Sie gehören, welchen Integrationsmodus Sie nutzen, was im wsa-Token enthalten ist und „bis zu welchem Grad" Sie es verwenden möchten.

Zwei Integrationsmodi: Push vs. Pull

Es gibt zwei Wege, auf denen die Plattform Ihnen die Identität übergibt. Es gilt derselbe wsa-Vertrag, der Unterschied liegt nur darin, „wie Sie die Identitätsauthentifizierungsinformationen erhalten".

Push (Push handoff) – siehe 03

Nutzer:innen öffnen Ihre App auf der Workspace-Seite „Erweiterungen", und die Plattform hängt das wsa an die URL Ihrer Landingpage an und pusht es an Sie:

https://app.example.com/landing?wsa=<JWT>

                      
                      https://app.example.com/landing?wsa=<JWT>

Dieser Codeblock im schwebenden Fenster

Der Einstieg liegt innerhalb des Workspace.
Entwickler:innen müssen lediglich das ?wsa= auf der Landingpage konsumieren – am einfachsten.
Geeignet für: eine „eingebettete App" in der Workspace-Seitenleiste.

Pull (Pull / M-Auth) – siehe 04

Die Erweiterungs-App der Entwickler:innen platziert selbst einen „Login with Workspace"-Button. Nach dem Klick gelangen Nutzer:innen zur GPTBots-Anmeldung ➡️ wählen einen Workspace aus ➡️ und werden mit ihrem Anmeldezustand zurückgebracht. Es kommt OAuth2-Autorisierungscode + PKCE zum Einsatz:

Der Einstieg liegt auf der Anmeldeseite der Erweiterungs-App der Entwickler:innen.
Der Browser erhält nur einen einmaligen code; das eigentliche wsa wird von Ihrem Backend mit code + PKCE eingetauscht und gelangt nie in die Browser-URL.
Geeignet für: Die Erweiterungs-App der Entwickler:innen ist eine eigenständige Website und möchte eine „Anmeldung mit dem GPTBots-Workspace-Konto" anbieten.

	Push	Pull (M-Auth)
Anmelde-Einstieg	Workspace-Seite „Erweiterungen"	Ihre App-Seite (Anmelde-Button)
Wie das Token zu Ihnen gelangt	Direkt per URL `?wsa=` an die Landingpage gepusht	Frontend erhält `code`, Backend tauscht `wsa`
Sieht der Browser das `wsa`	Ja (nach dem Landen sofort entfernen)	Nie (sicherer)
PKCE erforderlich	Nein	Ja (verpflichtend `S256`)
Frontend-SDK-Methode	`consumeHandoff`	`startWorkspaceLogin` + `completeWorkspaceLogin`

Leitfaden zur Verwendung der Identitätsauthentifizierungsinformationen

Die Plattform ist nur für die „Übergabe der Identität" zuständig, ob sie verwendet wird, entscheiden Entwickler:innen eigenständig:

Stufe	Bedeutung	Was Entwickler:innen tun müssen
`use`	Signatur prüfen + Session aufbauen + Funktionen anhand von `role` freischalten	`consumeHandoff` / `completeWorkspaceLogin`, im Backend `verifyWsa`
`receive-only`	Identität zur Anzeige/Analyse lesen, aber keine Session aufbauen, keine Freischaltung – weiterhin eigene Authentifizierung oder anonym nutzen	Nur `readHandoffToken()` (reine Funktion, ohne Seiteneffekte)
`ignore`	Gar nicht lesen, entspricht `auth_mode=none`, also nur ein gewöhnlicher externer Link	Nichts tun

verifyWsa / readHandoffToken sind beide reine Funktionen, daher ist „empfangen, aber nicht verwenden" kostenlos.

Entsprechend dem auth_mode bei der Registrierung:

auth_mode = workspace_account: Die Plattform signiert ein wsa und hängt es an die URL an (Push) / unterstützt M-Auth (Pull), sodass Sie die Identität erhalten.
auth_mode = none: Die Plattform leitet direkt weiter, die URL enthält keinerlei Authentifizierungsinformationen, und Sie erhalten keine Identität (entspricht ignore).

`wsa`-Token-Vertrag (JWT)

Das wsa ist ein mit HS256 (HMAC-SHA256) signiertes JWT mit einer Gültigkeit von 5 Minuten (exp = iat + 300).

Standard-Claims

Claim	Typ	Beschreibung
`iss`	string	Fest `gptbots-workspace`, muss geprüft werden
`aud`	string	Host der Erweiterungs-App der Entwickler:innen (z. B. `app.example.com`), aus der Registrierungs-URL geparst, muss geprüft werden
`sub`	string	`accountId` der Workspace-Nutzer:innen, global eindeutig, kann als Primärschlüssel der Nutzer-ID auf Entwicklerseite dienen
`iat`	number(Sekunden)	Ausstellungszeitpunkt
`exp`	number(Sekunden)	Ablaufzeitpunkt, fest `iat + 300`, muss geprüft werden

Business-Claims

Claim	Typ	Beschreibung
`role`	string	`OWNER` / `ADMIN` / `MEMBER` – die Rolle der Nutzer:innen in diesem Workspace
`workspace_id`	string	Workspace-ID (also `projectId`), Schlüssel für die Mandantentrennung
`username`	string	Nutzer-Spitzname (kann fehlen)
`email`	string	Nutzer-E-Mail (kann fehlen)
`avatar`	string	Avatar-URL (kann fehlen)
`app_name`	string	Name der Erweiterungs-App, zu der dieser Sprung gehört (zur Auditierung nützlich, kann fehlen)

Fehlende Felder: username / email / avatar / app_name erscheinen nicht im Payload, wenn sie in den Quelldaten leer sind. Sehen Sie unbedingt eine Absicherung für leere Werte vor und gehen Sie nicht davon aus, dass sie zwangsläufig vorhanden sind.

Beispiel-Payload

{ "iss": "gptbots-workspace", "aud": "app.example.com", "sub": "65f7c8a1d8f3a40012345678", "iat": 1730000000, "exp": 1730000300, "username": "Max Mustermann", "email": "max.mustermann@example.com", "avatar": "https://cdn.example.com/avatar/u123.png", "role": "ADMIN", "workspace_id": "65a0000000000000000abcde", "app_name": "Vertragsprüfungssystem" }

                      
                      {
  "iss": "gptbots-workspace",
  "aud": "app.example.com",
  "sub": "65f7c8a1d8f3a40012345678",
  "iat": 1730000000,
  "exp": 1730000300,
  "username": "Max Mustermann",
  "email": "max.mustermann@example.com",
  "avatar": "https://cdn.example.com/avatar/u123.png",
  "role": "ADMIN",
  "workspace_id": "65a0000000000000000abcde",
  "app_name": "Vertragsprüfungssystem"
}