Skip to main content
Подключения — это учетные данные, которыми пользователь располагает для внешнего сервиса (Linear, GitHub, Slack, …). Ваше приложение определяет, как получают эти учетные данные — через провайдера подключения — и использует их во время выполнения для выполнения аутентифицированных вызовов к стороннему API. На данный момент поддерживается только OAuth 2.0. Будущие типы учетных данных (персональные токены доступа, ключи API, базовая аутентификация) будут подключаться к тому же интерфейсу — приложения, уже использующие defineConnectionProvider({ type: 'oauth', ... }) не потребуют миграции.
Провайдер подключения описывает процедуру OAuth-обмена, которая требуется вашему приложению. Пользователь нажимает “Добавить подключение” в настройках вашего приложения, подтверждает разрешения на экране согласия провайдера, и в его рабочем пространстве создается запись ConnectedAccount.Рабочей конфигурации нужны два файла — провайдер подключения и соответствующее объявление serverVariables в defineApplication, которое содержит учетные данные клиента OAuth.
src/connection-providers/linear-connection.ts
src/application.config.ts
Основные моменты:
  • name — это уникальная строка-идентификатор, используемая в listConnections({ providerName }) (kebab-case, должна соответствовать ^[a-z][a-z0-9-]*$).
  • displayName отображается на вкладке настроек приложения и в списке инструментов ИИ.
  • clientIdVariable / clientSecretVariable — это имена, а не значения — они должны совпадать с ключами, объявленными в defineApplication.serverVariables. Фактические client_id и client_secret вводятся администратором сервера через интерфейс регистрации приложения и никогда не коммитятся в ваш репозиторий.
  • Используйте serverVariables (не applicationVariables) — учетные данные OAuth являются общими для сервера, и на каждом сервере Twenty используется одно приложение OAuth.
  • Пока оба serverVariables не заполнены, на вкладке настроек приложения показывается подсказка “нужен администратор сервера”, а кнопка “Добавить подключение” отключена.
  • type: 'oauth' — единственное поддерживаемое сегодня значение. Дискриминатор совместим с будущими версиями: будущие типы ('pat', 'api-key', …) добавят новые блоки подконфигурации рядом с oauth.
URL обратного вызова OAuth, который вашему провайдеру нужно добавить в список разрешенных:
Некоторые провайдеры передают вам данные в момент подключения, которые нужно сохранить до того, как соединение станет пригодным к использованию — классический пример — Slack, где OAuth-ответ указывает team_id рабочей области, по которому будут определяться входящие события. Установите onConnectLogicFunction, чтобы сослаться на логическую функцию в том же приложении (по её universalIdentifier), и она будет выполнена сразу после создания ConnectedAccount.
src/connection-providers/slack-connection.ts
Хук выполняется асинхронно в подключающейся рабочей области (он ставится в очередь, а не ожидается), поэтому медленный или падающий хук никогда не блокирует и не ломает OAuth-callback — сделайте его идемпотентным и обеспечьте собственную обработку повторных попыток. Обработчик получает:
Оттуда используйте getConnection(connectedAccountId), чтобы прочитать новый access token и вызвать API провайдера (например, Slack auth.test) или сохранить отображение с помощью key-value store.
Всё, на что приложение заявляет права при подключении, должно быть освобождено, когда подключение прекращается. Интеграция со Slack, которая, например, заявляет team_id при подключении, должна освободить это право, чтобы другое рабочее пространство могло подключить ту же Slack-команду. Установите onDisconnectLogicFunction, чтобы сослаться на логическую функцию в том же приложении, и она будет выполнена сразу после удаления ConnectedAccount.
src/connection-providers/slack-connection.ts
Как и hook on-connect, он запускается асинхронно в отключаемом рабочем пространстве и никогда не блокирует отключение. Обработчик получает тот же формат полезной нагрузки:
ConnectedAccount уже удалён к моменту запуска hook, поэтому getConnection(connectedAccountId) больше не возвращает результат. Всё, что требуется для очистки (например, team_id, внешний идентификатор подписки), должно быть записано в key-value store в момент подключения, с ключом connectedAccountId.Hook срабатывает, когда соединение удаляется само по себе. При удалении приложения его соединения удаляются каскадом на уровне базы данных, поэтому hook в этом случае не запускается. Объявите uninstallLogicFunction в defineApplication для этого сценария: она запускается до удаления метаданных приложения, поэтому всё ещё может вызвать listConnections и выполнить оставшуюся очистку.
Внутри обработчика логической функции listConnections({ providerName }) возвращает записи ConnectedAccount этого приложения для указанного провайдера с обновленными токенами доступа.
src/logic-functions/handlers/create-linear-issue-handler.ts
Каждое подключение имеет:Основные моменты:
  • Передайте { providerName }, чтобы отфильтровать по провайдеру; опустите, чтобы получить все подключения этого приложения у всех провайдеров.
  • Сервер прозрачно обновляет токен доступа перед возвратом. Ваш обработчик всегда получает рабочий токен (или установлено authFailedAt).
  • getConnection(id) — эквивалент для одной записи.
Когда пользователь нажимает “Добавить подключение”, ему предлагается выбрать видимость:
  • Только для меня — учетные данные приватны для подключившегося пользователя. Любая логическая функция, вызываемая от его имени (триггер HTTP-маршрута с isAuthRequired: true), видит их; триггеры cron и события базы данных — нет.
  • Общее для рабочего пространства — любой участник рабочего пространства может использовать эти учетные данные. Триггеры cron/базы данных также видят их, поскольку у них нет пользователя запроса.
Используйте подходящий вариант для каждого обработчика:
Допускается несколько подключений на пару (пользователь, провайдер), поэтому один и тот же пользователь может иметь “Personal Linear” и “Work Linear” одновременно.
Для каждого провайдера подключения администратору сервера сначала нужно зарегистрировать у стороннего сервиса приложение OAuth.
  1. Перейдите в настройки разработчика провайдера (например, https://linear.app/settings/api/applications/new).
  2. Установите Redirect URI в значение \<SERVER_URL>/auth/apps/callback.
  3. Скопируйте сгенерированные Client ID и Client Secret.
  4. Откройте установленное приложение в Twenty под учетной записью администратора сервера → задайте значения в соответствующих serverVariables.
  5. Затем участники рабочего пространства смогут добавлять подключения в разделе Подключения конкретного приложения.