Saltar al contenido principal
Las conexiones son credenciales que un usuario posee para un servicio externo (Linear, GitHub, Slack, …). Tu aplicación declara cómo se obtienen esas credenciales — un proveedor de conexión — y las consume en tiempo de ejecución para realizar llamadas autenticadas a la API de terceros. Actualmente solo se admite OAuth 2.0. Los futuros tipos de credenciales (tokens de acceso personal, claves de API, autenticación básica) se integrarán en la misma interfaz — las aplicaciones que ya usan defineConnectionProvider({ type: 'oauth', ... }) no necesitarán migrar.
Un proveedor de conexión describe el flujo de OAuth que tu aplicación necesita. El usuario hace clic en “Agregar conexión” en la configuración de tu aplicación, completa la pantalla de consentimiento del proveedor y se crea una fila ConnectedAccount en su espacio de trabajo.Una configuración funcional necesita dos archivos — el proveedor de conexión y una declaración serverVariables correspondiente en defineApplication que contiene las credenciales del cliente OAuth.
src/connection-providers/linear-connection.ts
src/application.config.ts
Puntos clave:
  • name es la cadena de identificador única utilizada en listConnections({ providerName }) (kebab-case, debe coincidir con ^[a-z][a-z0-9-]*$).
  • displayName se muestra en la pestaña de configuración por aplicación y en la lista de herramientas de IA.
  • clientIdVariable / clientSecretVariable son nombres, no valores — deben coincidir con las claves declaradas en defineApplication.serverVariables. Los client_id y client_secret reales los introduce el administrador del servidor a través de la interfaz de registro de la aplicación; nunca se incluyen en tu repositorio.
  • Usa serverVariables (no applicationVariables) — las credenciales de OAuth son a nivel de servidor y hay una aplicación OAuth por servidor de Twenty.
  • Hasta que ambos serverVariables estén completos, la pestaña de configuración por aplicación muestra un aviso de “requiere administrador del servidor” y el botón “Agregar conexión” está deshabilitado.
  • type: 'oauth' es el único valor admitido actualmente. El discriminador es compatible hacia adelante: tipos futuros ('pat', 'api-key', …) agregarán nuevos bloques de subconfiguración junto a oauth.
La URL de callback de OAuth que tu proveedor debe autorizar es:
Dentro de un controlador de función de lógica, listConnections({ providerName }) devuelve las filas ConnectedAccount de esta aplicación para el proveedor indicado, con tokens de acceso actualizados.
src/logic-functions/handlers/create-linear-issue-handler.ts
Cada conexión tiene:Puntos clave:
  • Pasa { providerName } para filtrar por proveedor; omítelo para obtener todas las conexiones que posee esta aplicación en todos los proveedores.
  • El servidor actualiza de forma transparente el token de acceso antes de devolver la respuesta. Tu controlador siempre ve un token utilizable (o authFailedAt establecido).
  • getConnection(id) es el equivalente de una sola fila.
Cuando un usuario hace clic en “Agregar conexión”, se le solicita que elija una visibilidad:
  • Solo para mí — la credencial es privada para el usuario que se conecta. Cualquier función de lógica llamada en su nombre (activador de ruta HTTP con isAuthRequired: true) la ve; los activadores de cron y los eventos de base de datos no.
  • Compartida en el espacio de trabajo — cualquier miembro del espacio de trabajo puede usar la credencial. Los activadores de cron y de base de datos también la ven, ya que no tienen usuario de la solicitud.
Usa la adecuada para cada controlador:
Se permiten múltiples conexiones por (usuario, proveedor), por lo que el mismo usuario puede tener “Linear personal” y “Linear de trabajo” a la vez.
Para cada proveedor de conexión, el administrador del servidor debe registrar primero una aplicación OAuth en el servicio de terceros.
  1. Ve a la configuración de desarrollador del proveedor (p. ej., https://linear.app/settings/api/applications/new).
  2. Configura el URI de redirección en \<SERVER_URL>/auth/apps/callback.
  3. Copia el Client ID y el Client Secret generados.
  4. Abre la aplicación instalada en Twenty como administrador del servidor → establece los valores en los serverVariables correspondientes.
  5. Luego, los miembros del espacio de trabajo pueden agregar conexiones desde la sección Conexiones por aplicación.