Intégrations OAuth

Cette page s'adresse à l'IT lead qui déploie Gilbert dans une entreprise (équipe commerciale, agence, cabinet, opérations). Vous avez reçu les droits admin OAuth — votre rôle est de connecter les comptes provider qui alimentent les routines et les agents.

Cas typique : une agence immobilière connecte Google Workspace pour qu'une routine quotidienne lise les mails de l'équipe commerciale et prépare le briefing du matin. Optionnellement : GitHub pour lire un repo d'outils internes, LinkedIn pour publier des posts depuis une routine de communication.

Trois intégrations OAuth sont disponibles aujourd'hui. Toutes sont strictement rattachées au compte utilisateur qui a lancé le flow (user-strict) : si Alice et Bob veulent tous deux que Gilbert lise leur Gmail, ils ont chacun leur intégration.

Le flow OAuth Google est lancé depuis votre console personnelle. Les scopes demandés sont gmail.modify (lire + drafter, jamais d'envoi automatique) et calendar.events (lecture agenda).

1. Allez sur /console/me/integrations/google.
2. Cliquez Connecter Gmail + Calendar. Vous êtes redirigé vers l'écran de consent Google standard, avec la liste explicite des accès demandés.
3. Validez. Le callback OAuth fait un échange access_token + refresh_token contre votre code, puis les chiffre côté serveur avant insertion en DB. Le token brut ne traverse jamais le navigateur après ce point.
4. La page de retour affiche le statut Connectéavec votre adresse mail Google et indique si le refresh token a bien été émis (sans lui, l'accès expire après 1h).
5. À partir de là, les routines et agents des workspaces dont vous êtes membre voient automatiquement les tools Gmail + Calendar comme disponibles.

GitHub est strictement rattaché à votre compte utilisateur. Une fois connecté, vous pouvez lier des repos à n'importe quel workspace dont vous êtes membre — les routines de ce workspace utiliseront votreOAuth pour lire ces repos (sauf si un PAT par-repo est configuré pour les repos d'org).

1. Allez sur /console/me/integrations/github. Si vous êtes déjà arrivé sur Gilbert via Sign in with GitHub, l'intégration est probablement déjà active : vérifiez que le scope repo est bien accordé.
2. Cliquez Connecter GitHub. Scope demandé : repo (lecture des repos publics + privés que vous voyez).
3. Au retour, vérifiez la liste des scopes. Si seul public_repo est accordé, les repos privés ne seront pas lisibles — reconnectez avec repo complet.
4. Pour lier un repo à un workspace, allez sur /console/workspaces/{id} puis section Repos GitHub liés. Deux modes : picker OAuth (liste vos repos accessibles) ou PAT manuel(pour les repos d'une org sans OAuth installé).

LinkedIn permet à une routine de publier un post UGC en votre nom. Les scopes demandés : identité (openid profile email, nécessaire pour récupérer l'URN LinkedIn qui sert d'auteur) et w_member_social (créer des posts).

1. Allez sur /console/me/integrations/linkedin.
2. Cliquez Connecter LinkedIn. Vous êtes redirigé vers l'écran de consent LinkedIn. Validez les deux scopes.
3. Au retour, la page affiche votre photo + nom + URN LinkedIn. Les routines peuvent alors appeler publish_linkedin_post.

Le modèle de sécurité est volontairement simple à auditer : une clé par intégration, chiffrement standard, lecture serveur uniquement.

• Chiffrement AES-256-GCM (standard NIST, mode authentifié) avec une clé dédiée par intégration : GOOGLE_TOKEN_KEY, LINKEDIN_TOKEN_KEY, GITHUB_TOKEN_KEY. Compromettre une clé n'expose qu'un seul provider.
• Clés stockées en variables d'environnement Vercel, jamais commitées au repo. Format hex 32 bytes, générées avec openssl rand -hex 32.
• Lecture server-onlyvia le client Supabase service role. Les tokens chiffrés ne sont jamais exposés à un client navigateur après le premier consent — même l'utilisateur propriétaire ne peut pas les relire en clair depuis l'UI.
• RLS Postgres sur gilbert.user_integrations : une row n'est visible que par son propriétaire (user_id = auth.uid()). Le service role bypass uniquement pour les jobs serveur (refresh, exec routine).
• Format chiffré stocké en DB : iv.tag.ciphertext hex, avec une colonne encryption_key_version pour faire tourner les clés sans casser les rows existantes.

Chaque intégration porte les champs user_id (le propriétaire OAuth, immuable) et updated_at (dernier consent). Vous savez à tout moment : qui a connecté ce compte Google, à quelle date, avec quels scopes.

La page /console/me/integrations liste les intégrations actives de votre compte. La page d'un workspace, /console/workspaces/{id}/integrations, indique pour chaque provider si une intégration compatible est disponible parmi les membres du workspace.

Les rotations de tokens (refresh) et les révocations sont loggées dans la table gilbert.personal_events : oauth_token_refreshed à chaque refresh réussi, oauth_token_revokeddès qu'un refresh échoue côté provider. Trail conservé même après suppression de l'intégration.

Deux chemins, valables à tout moment :

Liens directs vers les consoles provider : myaccount.google.com/permissions, github.com/settings/applications, linkedin.com/psettings/permitted-services.

Dès qu'une intégration est active, les tools correspondants deviennent automatiquement disponibles aux routines et aux agents du workspace — pas de configuration manuelle par tool.

Pour la liste exhaustive des tools (avec arguments et exemples), voir Console · Routines et Console · Agents.

• Mon intégration est marquée revoked_at, je n'ai pourtant rien révoqué : le refresh token a expiré (typique LinkedIn après 60 jours sans utilisation, ou Google après un changement de mot de passe). Reconnectez l'intégration depuis /console/me/integrations/{provider} avec consent forcé. Le précédent revoked_at reste loggé dans personal_eventspour l'audit.
• Le tool gmail_list_recent retourne une liste vide : vérifiez d'abord les scopes accordés (page intégration Google). Si gmail.modifyn'est pas dans la liste, reconnectez. Sinon, c'est que le compte connecté n'a effectivement aucun mail récent matchant les filtres par défaut (boîte de réception, non lus, 30 derniers jours) — testez avec gmail_search sur une requête plus large.
• repo_search retourne HTTP 403 : le token GitHub n'a pas les scopes requis pour la Code Search API sur des repos d'org. Solutions : (1) reconnecter GitHub en demandant repocomplet ; (2) pour un repo d'org avec SSO obligatoire, configurer un PAT par-repo depuis /console/workspaces/{id} > Repos GitHub liés.
• publish_linkedin_post échoue avec "refresh failed" : LinkedIn a invalidé votre refresh token (typiquement après 60 jours d'inactivité, ou si le mot de passe LinkedIn a changé). Reconnectez. Si l'erreur persiste, le quota daily API LinkedIn peut être atteint sur l'app — patientez 24h ou contactez le support.

Plus de cas : Troubleshooting (CSP, JWT rejeté, signature webhook, CORS, rate limit).

• Console B2B — vue d'ensemble workspaces, agents, repos, routines, MCP.
• Modèle mental — workspace, modes auth, isolation des données.
• JWT SSO — authentifier les utilisateurs de votre app auprès de Gilbert.