Concepts clés

Ce guide aide les développeurs à comprendre : à quelle couche d'extension vous appartenez, quel mode d'intégration vous suivez, ce que contient le jeton wsa, et « jusqu'à quel point » vous voulez l'utiliser.

Deux modes d'intégration : push vs pull

La plateforme vous transmet l'identité par deux chemins possibles. Le même contrat wsa, la seule différence étant « comment vous obtenez les informations d'authentification d'identité ».

Push (Push handoff) — voir 03

L'utilisateur ouvre votre application depuis la page « Extensions » de l'espace de travail, et la plateforme accroche le wsa à l'URL de votre page d'atterrissage pour vous le pousser :

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

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

Ce bloc de code dans la fenêtre flottante

Le point d'entrée est à l'intérieur de l'espace de travail.
Le développeur n'a qu'à consommer le ?wsa= sur la page d'atterrissage, c'est le plus simple.
Convient à : une « application embarquée » dans la barre latérale de l'espace de travail.

Pull (Pull / M-Auth) — voir 04

L'application d'extension du développeur affiche elle-même un bouton « Login with Workspace » ; après avoir cliqué, l'utilisateur accède à la connexion GPTBots ➡️ choisit un espace de travail ➡️ revient avec l'état de connexion. Utilise le code d'autorisation OAuth2 + PKCE :

Le point d'entrée est sur la page de connexion de l'application d'extension du développeur.
Le navigateur n'obtient qu'un code à usage unique ; le véritable wsa est échangé par votre backend à l'aide du code + PKCE, et n'entre jamais dans l'URL du navigateur.
Convient à : le cas où l'application d'extension du développeur est un site indépendant qui souhaite proposer « Se connecter avec un compte d'espace de travail GPTBots ».

	Push	Pull (M-Auth)
Point d'entrée de connexion	Page « Extensions » de l'espace de travail	Page de votre application (bouton de connexion)
Comment le jeton vous parvient	L'URL `?wsa=` est poussée directement vers la page d'atterrissage	Le frontend obtient le `code`, le backend échange le `wsa`
Le navigateur voit-il le `wsa`	Oui (à effacer immédiatement après l'atterrissage)	Jamais (plus sûr)
Nécessite PKCE	Non	Oui (`S256` obligatoire)
Méthode frontend du SDK	`consumeHandoff`	`startWorkspaceLogin` + `completeWorkspaceLogin`

Guide d'utilisation des informations d'authentification d'identité

La plateforme se charge uniquement de « transmettre l'identité » ; c'est au développeur de décider indépendamment s'il l'utilise :

Niveau	Signification	Ce que le développeur doit faire
`use`	Vérifier la signature + établir une session + contrôler l'accès aux fonctionnalités selon le `role`	`consumeHandoff` / `completeWorkspaceLogin`, `verifyWsa` côté backend
`receive-only`	Lire l'identité pour l'affichage/le tracking, sans créer de session ni de contrôle d'accès, en continuant avec sa propre authentification ou en anonyme	Uniquement `readHandoffToken()` (fonction pure, sans effet de bord)
`ignore`	Ne rien lire du tout, équivalent à `auth_mode=none`, c'est un simple lien externe	Ne rien faire

verifyWsa / readHandoffToken sont tous deux des fonctions pures, donc « recevoir sans utiliser » n'a aucun coût.

Correspondance avec l'auth_mode défini à l'enregistrement :

auth_mode = workspace_account : la plateforme signe le wsa et l'accroche à l'URL (push) / prend en charge M-Auth (pull), et vous pouvez obtenir l'identité.
auth_mode = none : la plateforme redirige directement, l'URL ne contient aucune information d'authentification, et vous ne recevez pas l'identité (correspond à ignore).

Contrat du jeton `wsa` (JWT)

Le wsa est un JWT signé en HS256 (HMAC-SHA256), valable 5 minutes (exp = iat + 300).

Claims standard

Claim	Type	Description
`iss`	string	Fixé à `gptbots-workspace`, vérification obligatoire
`aud`	string	Host de l'application d'extension du développeur (ex. `app.example.com`), extrait de l'URL enregistrée, vérification obligatoire
`sub`	string	`accountId` de l'utilisateur de l'espace de travail, unique globalement, peut servir de clé primaire d'ID utilisateur côté développeur
`iat`	number (secondes)	Heure d'émission
`exp`	number (secondes)	Heure d'expiration, fixée à `iat + 300`, vérification obligatoire

Claims métier

Claim	Type	Description
`role`	string	`OWNER` / `ADMIN` / `MEMBER` — le rôle de l'utilisateur dans cet espace de travail
`workspace_id`	string	ID de l'espace de travail (c'est-à-dire `projectId`), clé d'isolation multi-tenant
`username`	string	Pseudo de l'utilisateur (peut être absent)
`email`	string	E-mail de l'utilisateur (peut être absent)
`avatar`	string	URL de l'avatar (peut être absent)
`app_name`	string	Nom de l'application d'extension correspondant à cette redirection (utile pour l'audit, peut être absent)

Champs absents : username / email / avatar / app_name n'apparaissent pas dans le payload lorsque les données source sont vides ; veillez donc à gérer les valeurs nulles et ne supposez pas qu'ils sont toujours présents.

Exemple de payload

{ "iss": "gptbots-workspace", "aud": "app.example.com", "sub": "65f7c8a1d8f3a40012345678", "iat": 1730000000, "exp": 1730000300, "username": "Jean Dupont", "email": "jean.dupont@example.com", "avatar": "https://cdn.example.com/avatar/u123.png", "role": "ADMIN", "workspace_id": "65a0000000000000000abcde", "app_name": "Système de Révision de Contrats" }

                      
                      {
  "iss": "gptbots-workspace",
  "aud": "app.example.com",
  "sub": "65f7c8a1d8f3a40012345678",
  "iat": 1730000000,
  "exp": 1730000300,
  "username": "Jean Dupont",
  "email": "jean.dupont@example.com",
  "avatar": "https://cdn.example.com/avatar/u123.png",
  "role": "ADMIN",
  "workspace_id": "65a0000000000000000abcde",
  "app_name": "Système de Révision de Contrats"
}