Skip to main content
Bağlantılar, bir kullanıcının harici bir hizmet için (Linear, GitHub, Slack, …) sahip olduğu kimlik bilgileridir. Uygulamanız bu kimlik bilgilerinin nasıl elde edildiğini — bir bağlantı sağlayıcısı — bildirir ve çalışma zamanında üçüncü taraf API’sine kimlik doğrulamalı çağrılar yapmak için bunları kullanır. Bugün yalnızca OAuth 2.0 destekleniyor. Gelecekteki kimlik bilgisi türleri (kişisel erişim belirteçleri, API anahtarları, basic auth) aynı yüzeye bağlanacak — halihazırda defineConnectionProvider({ type: 'oauth', ... }) kullanan uygulamaların geçiş yapması gerekmeyecek.
Bir bağlantı sağlayıcısı, uygulamanızın ihtiyaç duyduğu OAuth el sıkışmasını açıklar. Kullanıcı, uygulamanızın ayarlarında “Bağlantı ekle”ye tıklar, sağlayıcının izin ekranını tamamlar ve çalışma alanında bir ConnectedAccount satırı oluşturulur.Çalışan bir kurulum iki dosya gerektirir — bağlantı sağlayıcısı ve OAuth istemci kimlik bilgilerini tutan defineApplication üzerindeki eşleşen bir serverVariables bildirimi.
src/connection-providers/linear-connection.ts
src/application.config.ts
Önemli noktalar:
  • name, listConnections({ providerName }) içinde kullanılan benzersiz tanımlayıcı dizedir (kebab-case, ^[a-z][a-z0-9-]*$ ile eşleşmelidir).
  • displayName uygulama başına ayarlar sekmesinde ve Yapay Zeka araç listesinde gösterilir.
  • clientIdVariable / clientSecretVariable değer değil, isimdirdefineApplication.serverVariables içinde bildirilen anahtarlarla eşleşmelidir. Gerçek client_id ve client_secret, sunucu yöneticisi tarafından uygulama kayıt arayüzü üzerinden girilir; deponuza asla commit edilmez.
  • serverVariables kullanın (applicationVariables değil) — OAuth kimlik bilgileri sunucu genelidir ve her Twenty sunucusu için bir OAuth uygulaması vardır.
  • Her iki serverVariables da doldurulana kadar, uygulama başına ayarlar sekmesi “sunucu yöneticisine ihtiyaç var” ipucunu gösterir ve “Bağlantı ekle” düğmesi devre dışı bırakılır.
  • type: 'oauth' bugün desteklenen tek değerdir. Ayırt edici alan ileriye dönük uyumludur: gelecekteki türler ('pat', 'api-key', …) oauth yanında yeni alt yapılandırma blokları eklenecektir.
Sağlayıcınızın beyaz listeye alması gereken OAuth geri çağrı URL’si şudur:
Bazı sağlayıcılar, bağlantı anında size, bağlantı kullanılabilir hale gelmeden önce kalıcı hale getirmeniz gereken veriler verir — klasik örnek Slack’tir; burada OAuth yanıtı, gelen olayların anahtarlanacağı çalışma alanının team_id bilgisini sağlar. onConnectLogicFunction değerini, aynı uygulamadaki bir mantık fonksiyonuna (onun universalIdentifier değeriyle) referans verecek şekilde ayarlayın; böylece ConnectedAccount oluşturulduktan hemen sonra çalışır.
src/connection-providers/slack-connection.ts
Kanca, bağlanan çalışma alanında eşzamansız olarak çalışır (kuyruğa alınır, beklenmez), bu nedenle yavaşlayan veya başarısız olan bir kanca hiçbir zaman OAuth geri çağrısını engellemez veya bozmaz — onu idempotent yapın ve kendi tekrar denemelerini kendisi yönetsin. İşleyici şunları alır:
Buradan getConnection(connectedAccountId) kullanarak yeni erişim belirtecini okuyun ve sağlayıcının API’sini (ör. Slack auth.test) çağırın veya key-value store ile bir eşleme kalıcı hale getirin.
Bir uygulamanın bağlanma anında talep ettiği her şey, bağlantı sona erdiğinde serbest bırakılmalıdır. Örneğin, bağlanırken bir team_id talep eden bir Slack entegrasyonu, başka bir çalışma alanının aynı Slack ekibini bağlayabilmesi için bu talebi serbest bırakmak zorundadır. Aynı uygulamadaki bir mantık fonksiyonuna referans vermesi için onDisconnectLogicFunction değerini ayarlayın; böylece ConnectedAccount silindikten hemen sonra çalışır.
src/connection-providers/slack-connection.ts
Bağlanma kancası gibi, bağlantısı kesilmekte olan çalışma alanında eşzamansız olarak çalışır ve bağlantı kesme işlemini asla engellemez. İşleyici aynı payload biçimini alır:
Kanca çalıştığında ConnectedAccount zaten kaldırılmıştır, bu yüzden getConnection(connectedAccountId) artık sonuç döndürmez. Temizliğin ihtiyaç duyduğu her şey (team_id, harici abonelik kimliği gibi) bağlanma sırasında, connectedAccountId anahtarıyla key-value store içine yazılmış olmalıdır.Kanca, bir bağlantı kendi başına kaldırıldığında tetiklenir. Uygulamanın kaldırılması, bağlantılarını bunun yerine bir veritabanı zincirleme silme işlemiyle kaldırır, bu nedenle kanca burada çalışmaz. Bu yol için defineApplication üzerinde bir uninstallLogicFunction bildirin: bu işlev, uygulamanın meta verileri silinmeden önce çalışır, böylece hâlâ listConnections çağırabilir ve geride kalan her şeyi temizleyebilir.
Bir mantık işlevi işleyicisi içinde, listConnections({ providerName }), verilen sağlayıcı için bu uygulamanın ConnectedAccount satırlarını, yenilenmiş erişim belirteçleriyle döndürür.
src/logic-functions/handlers/create-linear-issue-handler.ts
Her bağlantı şunlara sahiptir:Önemli noktalar:
  • Sağlayıcıya göre filtrelemek için { providerName } iletin; bu uygulamanın tüm sağlayıcılardaki tüm bağlantılarını almak için bunu atlayın.
  • Sunucu, döndürmeden önce erişim belirtecini şeffaf bir şekilde yeniler. İşleyiciniz her zaman kullanılabilir bir belirteç görür (veya authFailedAt ayarlanmıştır).
  • getConnection(id), tek satırlık karşılığıdır.
Bir kullanıcı “Bağlantı ekle”ye tıkladığında, bir görünürlük seçmesi istenir:
  • Yalnızca benim için — kimlik bilgisi, bağlanan kullanıcıya özeldir. Adlarına çağrılan herhangi bir mantık işlevi (isAuthRequired: true ile HTTP rota tetikleyicisi) bunu görür; cron tetikleyicileri ve veritabanı olayları görmez.
  • Çalışma alanı paylaşımlı — herhangi bir çalışma alanı üyesi bu kimlik bilgisini kullanabilir. Cron / veritabanı tetikleyicileri de görür, çünkü istek kullanıcısı yoktur.
Her işleyici için doğru olanı kullanın:
Kullanıcı ve sağlayıcı başına birden çok bağlantıya izin verilir; böylece aynı kullanıcı “Personal Linear” ve “Work Linear” bağlantılarını yan yana tutabilir.
Her bağlantı sağlayıcısı için, sunucu yöneticisinin önce üçüncü tarafta bir OAuth uygulaması kaydetmesi gerekir.
  1. Sağlayıcının geliştirici ayarlarına gidin (örn. https://linear.app/settings/api/applications/new).
  2. Redirect URI’yi \<SERVER_URL>/auth/apps/callback olarak ayarlayın.
  3. Oluşturulan Client ID ve Client Secret’ı kopyalayın.
  4. Yüklü uygulamayı Twenty’de bir sunucu yöneticisi olarak açın → karşılık gelen serverVariables üzerinde değerleri ayarlayın.
  5. Ardından çalışma alanı üyeleri, uygulama başına Bağlantılar bölümünden bağlantılar ekleyebilir.