Skip to main content
Conexiunile sunt acreditări pe care un utilizator le deține pentru un serviciu extern (Linear, GitHub, Slack, …). Aplicația ta declară cum sunt obținute acele acreditări — un furnizor de conexiune — și le folosește în timpul execuției pentru a efectua apeluri autentificate către API-ul terț. În prezent este acceptat doar OAuth 2.0. Tipurile viitoare de acreditări (jetoane de acces personale, chei API, autentificare de bază) se vor integra în aceeași interfață — aplicațiile care deja folosesc defineConnectionProvider({ type: 'oauth', ... }) nu vor trebui să migreze.
Un furnizor de conexiune descrie handshake-ul OAuth de care are nevoie aplicația ta. Utilizatorul face clic pe “Adaugă conexiune” în setările aplicației tale, completează ecranul de consimțământ al furnizorului și este creată o înregistrare ConnectedAccount în spațiul său de lucru.O configurație funcțională are nevoie de două fișiere — furnizorul de conexiune și o declarație serverVariables corespunzătoare în defineApplication care conține acreditările clientului OAuth.
src/connection-providers/linear-connection.ts
src/application.config.ts
Puncte cheie:
  • name este șirul identificator unic folosit în listConnections({ providerName }) (kebab-case, trebuie să corespundă ^[a-z][a-z0-9-]*$).
  • displayName apare în fila de setări a aplicației și în lista de instrumente AI.
  • clientIdVariable / clientSecretVariable sunt nume, nu valori — trebuie să se potrivească cheilor declarate în defineApplication.serverVariables. Valorile reale client_id și client_secret sunt introduse de administratorul serverului prin interfața de înregistrare a aplicației și nu sunt niciodată comise în repo-ul tău.
  • Folosește serverVariables (nu applicationVariables) — acreditările OAuth sunt la nivel de server și există o singură aplicație OAuth pentru fiecare server Twenty.
  • Până când ambele serverVariables sunt completate, fila de setări a aplicației afișează un indiciu “necesită administrator de server” și butonul “Adaugă conexiune” este dezactivat.
  • type: 'oauth' este singura valoare acceptată în prezent. Discriminatorul este compatibil cu versiuni viitoare: tipurile viitoare ('pat', 'api-key', …) vor adăuga blocuri noi de sub-configurație alături de oauth.
URL-ul de callback OAuth pe care furnizorul tău trebuie să îl includă pe lista albă este:
Unii furnizori îți furnizează date în momentul conectării, pe care trebuie să le stochezi înainte ca conexiunea să poată fi utilizată — exemplul clasic este Slack, unde răspunsul OAuth identifică team_id al spațiului de lucru după care vor fi indexate evenimentele primite. Setează onConnectLogicFunction pentru a face referire la o funcție logică din aceeași aplicație (prin universalIdentifier), iar aceasta rulează imediat după ce ConnectedAccount este creat.
src/connection-providers/slack-connection.ts
Hook-ul rulează asincron în spațiul de lucru care se conectează (este pus în coadă, nu este așteptat), astfel încât un hook lent sau care eșuează nu blochează și nu întrerupe niciodată callback-ul OAuth — fă-l idempotent și lasă-l să își gestioneze singur reîncercările. Handlerul primește:
De acolo folosește getConnection(connectedAccountId) pentru a citi tokenul de acces proaspăt și a apela API-ul furnizorului (de ex. Slack auth.test) sau pentru a stoca o mapare în magazinul cheie–valoare.
Orice revendică o aplicație la momentul conectării trebuie eliberat atunci când conexiunea este eliminată. O integrare Slack care revendică un team_id la conectare, de exemplu, trebuie să elibereze acea revendicare astfel încât un alt spațiu de lucru să poată conecta aceeași echipă Slack. Setează onDisconnectLogicFunction pentru a face referire la o funcție logică din aceeași aplicație, iar aceasta rulează imediat după ce ConnectedAccount este șters.
src/connection-providers/slack-connection.ts
La fel ca hook-ul on-connect, acesta rulează asincron în spațiul de lucru care se deconectează și nu blochează niciodată deconectarea. Handler-ul primește aceeași structură de payload:
ConnectedAccount nu mai există atunci când rulează hook-ul, astfel încât getConnection(connectedAccountId) nu se mai rezolvă. Tot ceea ce îi este necesar procesului de curățare (un team_id, un ID extern de abonament) trebuie să fi fost scris în key-value store la momentul conectării, indexat după connectedAccountId.Hook-ul este declanșat atunci când o conexiune este eliminată în mod direct. Dezinstalarea aplicației elimină conexiunile acesteia printr-un mecanism în cascadă în baza de date, astfel încât hook-ul nu rulează în acest caz. Declară un uninstallLogicFunction pe defineApplication pentru acel flux: acesta rulează înainte ca metadatele aplicației să fie șterse, astfel încât poate apela în continuare listConnections și poate curăța tot ce a mai rămas.
În interiorul unui handler de funcție logică, listConnections({ providerName }) returnează înregistrările ConnectedAccount ale acestei aplicații pentru furnizorul dat, cu tokenuri de acces reîmprospătate.
src/logic-functions/handlers/create-linear-issue-handler.ts
Fiecare conexiune are:Puncte cheie:
  • Pasează { providerName } pentru a filtra după furnizor; omite-l pentru a obține toate conexiunile pe care această aplicație le deține la toți furnizorii.
  • Serverul reîmprospătează transparent tokenul de acces înainte de a returna. Handlerul tău vede întotdeauna un token utilizabil (sau authFailedAt setat).
  • getConnection(id) este echivalentul pentru o singură înregistrare.
Când un utilizator face clic pe “Adaugă conexiune”, i se solicită să aleagă o vizibilitate:
  • Doar pentru mine — acreditarea este privată pentru utilizatorul care se conectează. Orice funcție logică apelată în numele lor (declanșator de rută HTTP cu isAuthRequired: true) o vede; declanșatoarele cron și evenimentele din bază de date nu.
  • Partajată la nivel de spațiu de lucru — orice membru al spațiului de lucru poate folosi acreditarea. Declanșatoarele cron / din bază de date o văd, de asemenea, deoarece nu au un utilizator al cererii.
Folosește-o pe cea potrivită pentru fiecare handler:
Sunt permise mai multe conexiuni per (utilizator, furnizor), astfel încât același utilizator poate avea “Personal Linear” și “Work Linear” una lângă alta.
Pentru fiecare furnizor de conexiune, administratorul serverului trebuie mai întâi să înregistreze o aplicație OAuth la serviciul terț.
  1. Mergi la setările pentru dezvoltatori ale furnizorului (de ex. https://linear.app/settings/api/applications/new).
  2. Setează Redirect URI la \<SERVER_URL>/auth/apps/callback.
  3. Copiază Client ID și Client Secret generate.
  4. Deschide aplicația instalată în Twenty ca administrator de server → setează valorile pe serverVariables corespunzătoare.
  5. Membrii spațiului de lucru pot apoi să adauge conexiuni din secțiunea Conexiuni a fiecărei aplicații.