Skip to main content
Le connessioni sono credenziali che un utente detiene per un servizio esterno (Linear, GitHub, Slack, …). La tua app dichiara come vengono ottenute tali credenziali — un provider di connessione — e le utilizza in fase di esecuzione per effettuare chiamate autenticate all’API di terze parti. Oggi è supportato solo OAuth 2.0. Tipi di credenziali futuri (token di accesso personali, chiavi API, autenticazione di base) si integreranno nella stessa interfaccia — le app che già usano defineConnectionProvider({ type: 'oauth', ... }) non dovranno migrare.
Un provider di connessione descrive l’handshake OAuth di cui la tua app ha bisogno. L’utente fa clic su “Aggiungi connessione” nelle impostazioni della tua app, completa la schermata di consenso del provider e viene creata una riga ConnectedAccount nel suo spazio di lavoro.Una configurazione funzionante richiede due file — il provider di connessione e una dichiarazione serverVariables corrispondente su defineApplication che contiene le credenziali client OAuth.
src/connection-providers/linear-connection.ts
src/application.config.ts
Punti chiave:
  • name è la stringa identificativa univoca usata in listConnections({ providerName }) (kebab-case, deve corrispondere a ^[a-z][a-z0-9-]*$).
  • displayName viene mostrato nella scheda delle impostazioni per app e nell’elenco degli strumenti AI.
  • clientIdVariable / clientSecretVariable sono nomi, non valori — devono corrispondere alle chiavi dichiarate in defineApplication.serverVariables. I client_id e client_secret effettivi vengono inseriti dall’amministratore del server tramite l’interfaccia di registrazione dell’app e non vengono mai aggiunti al tuo repository.
  • Usa serverVariables (non applicationVariables) — le credenziali OAuth sono a livello di server e c’è una sola app OAuth per ogni server Twenty.
  • Finché entrambe le serverVariables non sono compilate, la scheda delle impostazioni per app mostra un suggerimento “richiede l’amministratore del server” e il pulsante “Aggiungi connessione” è disattivato.
  • type: 'oauth' è l’unico valore supportato oggi. Il discriminatore è compatibile con versioni future: tipi futuri ('pat', 'api-key', …) aggiungeranno nuovi blocchi di sotto-configurazione accanto a oauth.
L’URL di callback OAuth che il tuo provider deve inserire nella whitelist è:
Alcuni provider ti forniscono dati al momento della connessione che devi memorizzare prima che la connessione sia utilizzabile — l’esempio classico è Slack, dove la risposta OAuth identifica il team_id dell’area di lavoro che fungerà da chiave per gli eventi in ingresso. Imposta onConnectLogicFunction per fare riferimento a una funzione logica nella stessa app (tramite il suo universalIdentifier), e questa verrà eseguita subito dopo la creazione di ConnectedAccount.
src/connection-providers/slack-connection.ts
L’hook viene eseguito in modo asincrono nell’area di lavoro che si sta connettendo (viene messo in coda, non atteso), quindi un hook lento o che fallisce non blocca né interrompe mai il callback OAuth — rendilo idempotente e fai in modo che gestisca autonomamente i propri tentativi di ripetizione. Il gestore riceve:
Da lì usa getConnection(connectedAccountId) per leggere il token di accesso aggiornato e chiamare l’API del provider (ad es. Slack auth.test) o salvare una mappatura con il key-value store.
All’interno di un gestore di funzione di logica, listConnections({ providerName }) restituisce le righe ConnectedAccount di questa app per il provider indicato, con token di accesso aggiornati.
src/logic-functions/handlers/create-linear-issue-handler.ts
Ogni connessione ha:Punti chiave:
  • Passa { providerName } per filtrare per provider; omettilo per ottenere tutte le connessioni possedute da questa app su tutti i provider.
  • Il server rinnova in modo trasparente il token di accesso prima di restituire la risposta. Il tuo handler vede sempre un token utilizzabile (oppure authFailedAt impostato).
  • getConnection(id) è l’equivalente a singola riga.
Quando un utente fa clic su “Aggiungi connessione”, viene richiesto di scegliere una visibilità:
  • Solo per me — la credenziale è privata per l’utente che effettua la connessione. Qualsiasi funzione di logica chiamata per loro conto (trigger di route HTTP con isAuthRequired: true) la vede; i trigger cron e gli eventi del database no.
  • Condivisa nello spazio di lavoro — qualsiasi membro dello spazio di lavoro può usare la credenziale. Anche i trigger cron/database la vedono, poiché non hanno un utente della richiesta.
Usa quella giusta per ciascun handler:
Sono consentite più connessioni per (utente, provider), quindi lo stesso utente può avere affiancate “Linear personale” e “Linear di lavoro”.
Per ciascun provider di connessione, l’amministratore del server deve prima registrare un’app OAuth presso il servizio di terze parti.
  1. Vai alle impostazioni sviluppatore del provider (ad es. https://linear.app/settings/api/applications/new).
  2. Imposta la Redirect URI su \<SERVER_URL>/auth/apps/callback.
  3. Copia il Client ID e il Client Secret generati.
  4. Apri l’app installata in Twenty come amministratore del server → imposta i valori nelle corrispondenti serverVariables.
  5. I membri dello spazio di lavoro possono quindi aggiungere connessioni dalla sezione Connessioni dell’app.