Inviter des membres dans un workspace

Cette page s'adresse au lead ITqui vient de créer un workspace Gilbert et qui doit y ajouter son équipe — typiquement 3 à 15 personnes (commerciaux, gestionnaires, support, ops). Tu sais déjà ce qu'est un workspace (sinon, lis Workspaces avant) ; tu veux savoir comment leur donner accès proprement, qui peut quoi, et comment éviter de t'auto-éjecter de ton propre workspace.

Si tu cherches à dérouler le déploiement complet pour une équipe (workspace + intégrations + invités + onboarding), lis aussi le tutoriel déploiement équipe.

• Être admin du workspace. Le créateur est admin par défaut. Si tu n'es que member, l'API renvoie 403 admin_requiredet l'UI cache le formulaire.
• L'email de connexion de l'invité. C'est cet email qui matche son compte Gilbert (auth Supabase). Pas forcément son email pro — voir Cas particuliers.
• Savoir son rôle cible (admin ou member). Tu peux changer plus tard, mais autant le poser correctement dès l'invite.

1. Tu ouvres ton workspace /console/workspaces/<id>. Section Membres, formulaire Inviter un membre : un champ email, un select rôle, un bouton Inviter.
2. Tu saisis l'email + le rôle, tu cliques Inviter. Le serveur (POST /api/console/workspaces/[id]/invite) résout d'abord : est-ce que ce user existe déjà ? via la RPC find_user_by_email.
   • Cas A — user inexistant. Gilbert appelle auth.admin.inviteUserByEmail. Supabase envoie un magic link, avec pending_workspace_id et pending_workspace_role embarqués dans son user_metadata. L'UI affiche « Invitation envoyée par email. »
   • Cas B — user déjà inscrit. Insert direct dans gilbert.workspace_members, puis Postmark envoie une notification transactionnelle « X t'a ajouté au workspace Y »avec un bouton vers le workspace. L'UI affiche « Membre ajouté. Notification envoyée par email. »
3. L'invité clique le lien dans son mail. Magic link → /auth/callback → vérification OTP. Si pending_workspace_id est dans son user_metadata, le callback appelle attachPendingWorkspaceMembership qui INSERT la membership et clear les fields pending_* (idempotent : re-cliquer le lien deux fois ne crée pas de doublon).
4. L'invité atterrit sur le workspace /console/workspaces/<id>. Il voit le workspace dans son switcher en haut du chat. Il peut commencer à l'utiliser immédiatement.

Pour scripter l'invite depuis ton terminal (test ou provisionning) :

curl -X POST https://gilbert.solveholding.com/api/console/workspaces/<workspace-id>/invite \
  -H "content-type: application/json" \
  -H "cookie: <ta-session-cookie>" \
  -d '{ "email": "marie@acme-immo.fr", "role": "member" }'

# 202 Accepted (user inexistant, magic link envoyé)
# { "invited": true, "user_exists": false, "magic_link_sent": true }

# 201 Created (user déjà inscrit, membership ajoutée + notif Postmark)
# { "invited": true, "user_exists": true, "already_member": false,
#   "notification_sent": true }

Deux rôles seulement en V1, volontairement. Pas de rôles custom, pas de matrice de permissions à 12 colonnes.

Règle pratique : tu mets admin pour tout copilote IT qui doit pouvoir débloquer / re-provisionner / fix une intégration, et member pour tout le monde qui consomme le produit au quotidien.

Toujours dans /console/workspaces/<id>, le tableau Membresliste tous les utilisateurs du workspace avec leur email, leur rôle, leur date d'arrivée.

• Changer le rôle. Select dans la colonne rôle — PATCH /api/console/workspaces/[id]/members/[userId]. Mise à jour instantanée, le membre voit la nouvelle capacité dès son prochain reload.
• Retirer un membre. Icône poubelle → bouton Retirer de confirmation → DELETE /api/console/workspaces/[id]/members/[userId]. Il perd l'accès au workspace immédiatement (mais conserve son compte Gilbert et ses autres workspaces).
• Te retirer toi-même. Pas via cette UI : ta ligne n'a pas de bouton Retirer. Si tu veux vraiment quitter, fais-toi retirer par un autre admin.

• Email de login ≠ email pro. L'email qui compte pour la membership, c'est celui auquel le user se connecte à Gilbert (auth Supabase). Si Marie se connecte à Gilbert avec marie.dupont@gmail.com mais bosse sous marie@acme-immo.fr, invite-la sous son email Gmail — sinon le magic link arrive sur la boîte pro mais ne matche aucun compte. Le cas « forwarder depuis l'email pro »(Postmark inbound) est géré séparément via forward_alias_email côté membership, voir Forward-to-Gilbert.
• L'invité a déjà un compte Gilbert mais a perdu l'accès à sa boîte. La notif Postmark n'est pas bloquante : il sera ajouté quand même, le workspace apparaîtra dans son switcher à sa prochaine connexion. L'UI affiche « Membre ajouté (notification email indisponible — il verra le workspace à sa prochaine connexion). »
• Postmark indispo / quota dépassé. L'envoi du mail est fire-and-forgetcôté serveur : la membership est créée, l'erreur Postmark est loggée mais l'invite renvoie 201 avec notification_sent: false. À toi de prévenir le membre manuellement (Slack, SMS, peu importe).
• La personne est déjà membre. Le serveur détecte la unique_violation Postgres (PK (workspace_id, user_id)) et renvoie already_member: true. L'UI affiche « Cette personne est déjà membre. » Aucune action côté DB, aucun mail envoyé.
• L'invité clique le magic link deux fois. attachPendingWorkspaceMembership ignore les unique_violation et redirige quand même vers le workspace. Idempotent par design.

La logique de rôles ne tient pas dans l'UI : tout est vérifié côté serveur via workspaceMemberGuard.ts, qui expose deux helpers que toutes les routes /api/console/workspaces/[id]/* doivent utiliser.

• requireWorkspaceMember(workspaceId) — toute personne membre passe (admin ou member). Sinon 401 unauthorized (pas de session) ou 404 not_member_of_workspace(réponse opaque pour ne pas leaker l'existence du workspace).
• requireWorkspaceAdmin(workspaceId) — seul un admin passe. Un member du même workspace reçoit 403 admin_required.
• Last-admin protection. Les routes PATCH et DELETE sur /members/[userId] font un countexact des admins avant d'agir. Si l'opération laisserait count == 0, on renvoie 409 last_admin.
• Isolation cross-workspace. Toutes les requêtes membres scopent par workspace_id dans le schéma gilbert. Aucun moyen, depuis le workspace A, de lister ou de modifier les membres du workspace B — même si tu connais l'UUID du B.
• RPC SECURITY DEFINER. Le lookup user-by-email (find_user_by_email) et la liste enrichie email-rôle (list_workspace_members_with_email) sont des fonctions SECURITY DEFINERqui appliquent leur propre check d'auth — pas d'accès direct à auth.users depuis le code applicatif.

• Un seul niveau d'admin. Pas de hiérarchie owner / billing-admin / workspace-admin. Tous les admins sont équivalents. Pour 3-15 personnes c'est largement suffisant ; si tu opères 50+ utilisateurs avec des sous-rôles, parle-nous.
• Pas de rôles custom. Tu ne peux pas créer un rôle « lecture seule » ou « peut gérer les routines mais pas les intégrations ». Le jour où ça devient nécessaire, on ajoutera une matrice de permissions plutôt que d'étendre l'enum.
• Pas de bulk invite. Pas d'upload CSV, pas d'import depuis Google Workspace. À 15 personnes maximum, un email à la fois reste plus rapide qu'un import à débugger. Si tu invites 200 personnes, écris-nous, on te fera un script.
• Pas de SSO SAML / SCIM. Pas encore. La roadmap prévoit SSO + provisioning automatique pour les comptes ≥ 50 utilisateurs où chaque arrivée / départ RH doit être synchronisée sans intervention IT. Pour V1, l'invite manuelle email-par-email reste la seule porte d'entrée.