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, который вашему провайдеру нужно добавить в список разрешенных:
Внутри обработчика логической функции 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. Затем участники рабочего пространства смогут добавлять подключения в разделе Подключения конкретного приложения.