Skip to main content
Verbindungen sind Anmeldedaten, die ein Benutzer für einen externen Dienst besitzt (Linear, GitHub, Slack, …). Ihre App legt fest, wie diese Anmeldedaten bezogen werden — ein Verbindungsanbieter — und verwendet sie zur Laufzeit, um authentifizierte Aufrufe an die Drittanbieter-API zu tätigen. Derzeit wird nur OAuth 2.0 unterstützt. Zukünftige Anmeldedatentypen (Personal Access Tokens, API-Schlüssel, Basic Auth) werden in dieselbe Oberfläche integriert — Apps, die bereits defineConnectionProvider({ type: 'oauth', ... }) müssen nicht migriert werden.
Ein Verbindungsanbieter beschreibt den OAuth-Handshake, den Ihre App benötigt. Der Benutzer klickt in den Einstellungen Ihrer App auf “Verbindung hinzufügen”, schließt den Zustimmungsbildschirm des Anbieters ab, und in seinem Arbeitsbereich wird eine ConnectedAccount-Zeile erstellt.Eine funktionierende Einrichtung benötigt zwei Dateien — den Verbindungsanbieter und eine passende serverVariables-Deklaration in defineApplication, die die OAuth-Client-Anmeldedaten enthält.
src/connection-providers/linear-connection.ts
src/application.config.ts
Hauptpunkte:
  • name ist die eindeutige Bezeichner-Zeichenfolge, die in listConnections({ providerName }) verwendet wird (kebab-case, muss ^[a-z][a-z0-9-]*$ entsprechen).
  • displayName wird im Einstellungs-Tab der jeweiligen App und in der KI-Toolliste angezeigt.
  • clientIdVariable / clientSecretVariable sind Namen, keine Werte — sie müssen den in defineApplication.serverVariables deklarierten Schlüsseln entsprechen. Die tatsächlichen client_id und client_secret werden vom Serveradministrator über die App-Registrierungsoberfläche eingegeben und niemals in Ihr Repository eingecheckt.
  • Verwenden Sie serverVariables (nicht applicationVariables) — OAuth-Anmeldedaten gelten serverweit und es gibt eine OAuth-App pro Twenty-Server.
  • Solange beide serverVariables nicht ausgefüllt sind, zeigt der Einstellungs-Tab pro App den Hinweis “Benötigt Server-Admin” an und der Button “Verbindung hinzufügen” ist deaktiviert.
  • type: 'oauth' ist derzeit der einzige unterstützte Wert. Der Diskriminator ist vorwärtskompatibel: zukünftige Typen ('pat', 'api-key', …) werden neue Unterkonfigurationsblöcke neben oauth hinzufügen.
Die OAuth-Callback-URL, die Ihr Anbieter auf die Whitelist setzen muss, lautet:
Einige Anbieter liefern dir beim Verbindungsaufbau Daten, die du persistieren musst, bevor die Verbindung nutzbar ist – das klassische Beispiel ist Slack, bei dem die OAuth-Antwort die team_id des Workspaces angibt, anhand derer eingehende Ereignisse zugeordnet werden. Setze onConnectLogicFunction so, dass auf eine Logikfunktion in derselben App (über ihren universalIdentifier) verwiesen wird; sie wird direkt nach dem Erstellen des ConnectedAccount ausgeführt.
src/connection-providers/slack-connection.ts
Der Hook wird asynchron im verbindenden Workspace ausgeführt (er wird in eine Warteschlange gestellt, nicht abgewartet), sodass ein langsamer oder fehlerhafter Hook niemals den OAuth-Callback blockiert oder unterbricht – mache ihn idempotent und lass ihn seine eigenen Wiederholungen handhaben. Der Handler erhält:
Verwenden Sie von dort getConnection(connectedAccountId), um das aktuelle Zugriffstoken auszulesen und die API des Anbieters aufzurufen (z. B. Slack auth.test) oder eine Zuordnung im Key-Value Store zu persistieren.
Alles, was eine App zum Zeitpunkt des Verbindungsaufbaus beansprucht, muss freigegeben werden, wenn die Verbindung endet. Eine Slack-Integration, die zum Beispiel beim Verbindungsaufbau eine team_id für sich beansprucht, muss diesen Anspruch wieder freigeben, damit ein anderer Arbeitsbereich dasselbe Slack-Team verbinden kann. Setze onDisconnectLogicFunction so, dass auf eine Logikfunktion in derselben App verwiesen wird; sie wird direkt nach dem Löschen des ConnectedAccount ausgeführt.
src/connection-providers/slack-connection.ts
Wie der On-Connect-Hook läuft er asynchron im Workspace, in dem die Trennung erfolgt, und blockiert die Trennung nie. Der Handler erhält dieselbe Payload-Struktur:
Der ConnectedAccount ist bereits entfernt, wenn der Hook ausgeführt wird, daher wird getConnection(connectedAccountId) nicht mehr aufgelöst. Alles, was die Bereinigung benötigt (eine team_id, eine externe Abonnement-ID), muss zum Zeitpunkt des Verbindungsaufbaus im Key-Value-Store gespeichert worden sein, indiziert nach connectedAccountId.Der Hook wird ausgelöst, wenn eine Verbindung eigenständig entfernt wird. Die Deinstallation der App entfernt ihre Verbindungen hingegen über eine Datenbankkaskade, sodass der Hook dort nicht ausgeführt wird. Deklariere eine uninstallLogicFunction in defineApplication für diesen Pfad: Sie wird ausgeführt, bevor die Metadaten der App gelöscht werden, sodass sie weiterhin listConnections aufrufen und den verbleibenden Rest bereinigen kann.
Innerhalb eines Logikfunktions-Handlers gibt listConnections({ providerName }) die ConnectedAccount-Zeilen dieser App für den angegebenen Anbieter zurück, mit aktualisierten Zugriffstoken.
src/logic-functions/handlers/create-linear-issue-handler.ts
Jede Verbindung hat:Hauptpunkte:
  • Übergeben Sie { providerName }, um nach Anbieter zu filtern; lassen Sie es weg, um alle Verbindungen dieser App über alle Anbieter hinweg zu erhalten.
  • Der Server aktualisiert das Zugriffstoken vor der Rückgabe transparent. Ihr Handler sieht stets ein verwendbares Token (oder authFailedAt ist gesetzt).
  • getConnection(id) ist das Pendant für eine einzelne Zeile.
Wenn ein Benutzer auf “Verbindung hinzufügen” klickt, wird er aufgefordert, eine Sichtbarkeit auszuwählen:
  • Nur für mich — die Anmeldedaten sind für den sich verbindenden Benutzer privat. Jede Logikfunktion, die in seinem/ihrem Auftrag aufgerufen wird (HTTP-Routen-Trigger mit isAuthRequired: true), sieht sie; Cron-Trigger und Datenbankereignisse nicht.
  • Im Arbeitsbereich geteilt — jedes Arbeitsbereichsmitglied kann die Anmeldedaten verwenden. Cron-/Datenbank-Trigger sehen sie ebenfalls, da sie keinen anfragenden Benutzer haben.
Verwenden Sie für jeden Handler die richtige Option:
Mehrere Verbindungen pro (Benutzer, Anbieter) sind erlaubt, sodass derselbe Benutzer “Persönliches Linear” und “Arbeits-Linear” nebeneinander haben kann.
Für jeden Verbindungsanbieter muss der Serveradministrator zunächst eine OAuth-App beim Drittanbieter registrieren.
  1. Gehen Sie zu den Entwickler-Einstellungen des Anbieters (z. B. https://linear.app/settings/api/applications/new).
  2. Setzen Sie die Redirect-URI auf \<SERVER_URL>/auth/apps/callback.
  3. Kopieren Sie die generierte Client ID und das Client Secret.
  4. Öffnen Sie die installierte App in Twenty als Serveradministrator → setzen Sie die Werte in den entsprechenden serverVariables.
  5. Mitglieder des Arbeitsbereichs können dann Verbindungen im Verbindungen-Abschnitt der jeweiligen App hinzufügen.