Skip to main content
Připojení jsou pověření, která uživatel uchovává pro externí službu (Linear, GitHub, Slack, …). Vaše aplikace deklaruje, jak se tato pověření získávají — poskytovatel připojení — a za běhu je používá k provádění ověřených volání na rozhraní API třetí strany. V současnosti je podporován pouze OAuth 2.0. Budoucí typy pověření (osobní přístupové tokeny, klíče API, základní autentizace) se připojí ke stejnému rozhraní — aplikace, které již používají defineConnectionProvider({ type: 'oauth', ... }) nebudou muset migrovat.
Poskytovatel připojení popisuje OAuth handshake, který vaše aplikace potřebuje. Uživatel klikne v nastavení vaší aplikace na “Přidat připojení”, projde souhlasovou obrazovkou poskytovatele a v jeho pracovním prostoru se vytvoří řádek ConnectedAccount.Funkční nastavení vyžaduje dva soubory — poskytovatele připojení a odpovídající deklaraci serverVariables v defineApplication, která obsahuje klientská pověření OAuth.
src/connection-providers/linear-connection.ts
src/application.config.ts
Hlavní body:
  • name je jedinečný identifikátor (řetězec) používaný v listConnections({ providerName }) (kebab-case, musí odpovídat ^[a-z][a-z0-9-]*$).
  • displayName se zobrazuje na kartě nastavení jednotlivé aplikace a v seznamu nástrojů AI.
  • clientIdVariable / clientSecretVariable jsou názvy, ne hodnoty — musí odpovídat klíčům deklarovaným v defineApplication.serverVariables. Skutečné client_id a client_secret zadává správce serveru prostřednictvím rozhraní pro registraci aplikace, nikdy se necommitují do vašeho repozitáře.
  • Použijte serverVariables (nikoli applicationVariables) — pověření OAuth jsou celoserverová a na jeden server Twenty je jedna aplikace OAuth.
  • Dokud nejsou vyplněny obě serverVariables, karta nastavení aplikace zobrazuje nápovědu “vyžaduje správce serveru” a tlačítko “Přidat připojení” je zakázané.
  • type: 'oauth' je dnes jediná podporovaná hodnota. Rozlišovač je kompatibilní do budoucna: budoucí typy ('pat', 'api-key', …) přidají nové podbloky konfigurace vedle oauth.
URL zpětného volání OAuth, kterou musí váš poskytovatel zařadit na seznam povolených, je:
Někteří poskytovatelé vám při připojení předají data, která je potřeba uložit dříve, než lze připojení používat — klasickým příkladem je Slack, kde odpověď OAuth určuje team_id pracovního prostoru, podle kterého budou příchozí události indexovány. Nastavte onConnectLogicFunction tak, aby odkazovala na logickou funkci ve stejné aplikaci (podle jejího universalIdentifier), a ta se spustí hned poté, co je vytvořen ConnectedAccount.
src/connection-providers/slack-connection.ts
Hook běží asynchronně v připojujícím se pracovním prostoru (je zařazen do fronty, nečeká se na něj), takže pomalý nebo chybující hook nikdy neblokuje ani nenaruší OAuth callback — udělejte jej idempotentní a zajistěte, aby sám zpracovával opakované pokusy. Obslužná funkce přijímá:
Odtud použijte getConnection(connectedAccountId) ke čtení čerstvého přístupového tokenu a zavolejte API poskytovatele (např. Slack auth.test) nebo uložte mapování pomocí úložiště klíč–hodnota.
Uvnitř handleru logické funkce vrací listConnections({ providerName }) řádky ConnectedAccount této aplikace pro daného poskytovatele s obnovenými přístupovými tokeny.
src/logic-functions/handlers/create-linear-issue-handler.ts
Každé připojení má:Hlavní body:
  • Předejte { providerName } pro filtrování podle poskytovatele; vynechejte jej, chcete-li získat všechna připojení, která tato aplikace vlastní napříč všemi poskytovateli.
  • Server před vrácením výsledku transparentně obnoví přístupový token. Váš handler vždy uvidí použitelný token (nebo nastavené authFailedAt).
  • getConnection(id) je jednořádkový ekvivalent.
Když uživatel klikne na “Přidat připojení”, je vyzván k výběru viditelnosti:
  • Jen pro mě — pověření je soukromé pro připojujícího se uživatele. Jakákoli logická funkce volaná jejich jménem (spouštěč HTTP trasy s isAuthRequired: true) jej uvidí; spouštěče cron a události databáze nikoli.
  • Sdíleno v pracovním prostoru — jakýkoli člen pracovního prostoru může pověření použít. Spouštěče cron/databáze jej také uvidí, protože nemají žádného uživatele požadavku.
Pro každý handler použijte tu správnou variantu:
Více připojení na (uživatele, poskytovatele) je povoleno, takže tentýž uživatel může mít vedle sebe “Personal Linear” a “Work Linear”.
Pro každého poskytovatele připojení musí správce serveru nejprve zaregistrovat u třetí strany aplikaci OAuth.
  1. Přejděte do vývojářského nastavení poskytovatele (např. https://linear.app/settings/api/applications/new).
  2. Nastavte Redirect URI na \<SERVER_URL>/auth/apps/callback.
  3. Zkopírujte vygenerované Client ID a Client Secret.
  4. Otevřete nainstalovanou aplikaci v Twenty jako správce serveru → nastavte hodnoty na odpovídajících serverVariables.
  5. Členové pracovního prostoru pak mohou přidávat připojení v sekci aplikace Připojení.