Skip to main content
Les connexions sont des identifiants qu’un utilisateur détient pour un service externe (Linear, GitHub, Slack, …). Votre application déclare comment ces identifiants sont obtenus — un fournisseur de connexion — et les consomme à l’exécution pour effectuer des appels authentifiés vers l’API tierce. À ce jour, seul OAuth 2.0 est pris en charge. De futurs types d’identifiants (jetons d’accès personnels, clés d’API, authentification de base) s’intégreront à la même interface — les applications utilisant déjà defineConnectionProvider({ type: 'oauth', ... })` n’auront pas besoin de migrer.
Un fournisseur de connexion décrit le processus d’échange OAuth requis par votre application. L’utilisateur clique sur “Ajouter une connexion” dans les paramètres de votre application, complète l’écran de consentement du fournisseur, et une ligne ConnectedAccount est créée dans son espace de travail.Une configuration fonctionnelle nécessite deux fichiers — le fournisseur de connexion, et une déclaration serverVariables correspondante sur defineApplication qui contient les identifiants client OAuth.
src/connection-providers/linear-connection.ts
src/application.config.ts
Points clés :
  • name est l’identifiant unique utilisé dans listConnections({ providerName }) (kebab-case, doit correspondre à ^[a-z][a-z0-9-]*$).
  • displayName s’affiche dans l’onglet des paramètres par application et dans la liste des outils d’IA.
  • clientIdVariable / clientSecretVariable sont des noms, pas des valeurs — ils doivent correspondre aux clés déclarées dans defineApplication.serverVariables. Les client_id et client_secret réels sont saisis par l’administrateur du serveur via l’interface d’enregistrement de l’application, et ne sont jamais validés dans votre dépôt.
  • Utilisez serverVariables (pas applicationVariables) — les identifiants OAuth sont au niveau du serveur et il n’y a qu’une application OAuth par serveur Twenty.
  • Tant que les deux serverVariables ne sont pas renseignées, l’onglet des paramètres par application affiche une indication “nécessite un administrateur du serveur” et le bouton “Ajouter une connexion” est désactivé.
  • type: 'oauth' est la seule valeur prise en charge à ce jour. Le discriminateur est compatible avec les évolutions : des types futurs ('pat', 'api-key', …) ajouteront de nouveaux blocs de sous-configuration à côté de oauth.
L’URL de rappel OAuth que votre fournisseur doit autoriser est :
Certains fournisseurs vous transmettent, au moment de la connexion, des données que vous devez conserver avant que la connexion ne soit exploitable — l’exemple classique est Slack, où la réponse OAuth identifie le team_id de l’espace de travail sur lequel les événements entrants seront indexés. Définissez onConnectLogicFunction pour référencer une fonction logique dans la même application (par son universalIdentifier), et elle s’exécute juste après la création du ConnectedAccount.
src/connection-providers/slack-connection.ts
Le hook s’exécute de manière asynchrone dans l’espace de travail en cours de connexion (il est mis en file d’attente, non attendu), de sorte qu’un hook lent ou défaillant ne bloque ni n’interrompt jamais le callback OAuth — rendez-le idempotent et faites en sorte qu’il gère ses propres réessais. Le gestionnaire reçoit :
À partir de là, utilisez getConnection(connectedAccountId) pour lire le jeton d’accès actualisé et appeler l’API du fournisseur (par exemple Slack auth.test) ou persister un mappage dans le stockage clé-valeur.
Dans un gestionnaire de fonction logique, listConnections({ providerName }) renvoie les lignes ConnectedAccount de cette application pour le fournisseur donné, avec des jetons d’accès actualisés.
src/logic-functions/handlers/create-linear-issue-handler.ts
Chaque connexion comporte :Points clés :
  • Passez { providerName } pour filtrer par fournisseur ; omettez-le pour obtenir toutes les connexions que cette application possède sur l’ensemble des fournisseurs.
  • Le serveur actualise de manière transparente le jeton d’accès avant de répondre. Votre gestionnaire voit toujours un jeton utilisable (ou authFailedAt défini).
  • getConnection(id) est l’équivalent pour une seule ligne.
Lorsqu’un utilisateur clique sur “Ajouter une connexion”, il lui est demandé de choisir une visibilité :
  • Uniquement pour moi — les identifiants sont privés pour l’utilisateur qui se connecte. Toute fonction logique appelée en son nom (déclencheur de route HTTP avec isAuthRequired: true) y a accès ; les déclencheurs cron et les événements de base de données n’y ont pas accès.
  • Partagé au niveau de l’espace de travail — tout membre de l’espace de travail peut utiliser les identifiants. Les déclencheurs cron / base de données y ont également accès, puisqu’ils n’ont pas d’utilisateur de requête.
Utilisez le bon pour chaque gestionnaire :
Plusieurs connexions par (utilisateur, fournisseur) sont autorisées, ainsi le même utilisateur peut avoir “Linear personnel” et “Linear professionnel” côte à côte.
Pour chaque fournisseur de connexion, l’administrateur du serveur doit d’abord enregistrer une application OAuth auprès du service tiers.
  1. Accédez aux paramètres développeur du fournisseur (par ex. https://linear.app/settings/api/applications/new).
  2. Définissez l’URI de redirection sur \<SERVER_URL>/auth/apps/callback.
  3. Copiez l’ID client et le Secret client générés.
  4. Ouvrez l’application installée dans Twenty en tant qu’administrateur du serveur → définissez les valeurs sur les serverVariables correspondantes.
  5. Les membres de l’espace de travail peuvent ensuite ajouter des connexions depuis la section Connexions par application.