> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conexiones

> Permite que tu aplicación actúe en nombre de un usuario en servicios de terceros mediante OAuth.

## Resumen

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.

OAuth 2.0 está integrado, ya sea con un cliente que usted mismo registra (`oauth`) o detectado desde el servicio (`oauth-discovery`). Los servicios que se autentican con un token que el usuario copia de su configuración usan un proveedor `api-key`. Los servicios con su propio flujo de conexión — una página de inicio de sesión alojada, un identificador de cuenta entregado mediante webhook — utilizan un proveedor `custom`, donde tu aplicación controla el flujo y Twenty conserva el usuario, el espacio de trabajo y la conexión guardada. Los futuros tipos de credenciales (autenticación básica) se integrarán en la misma interfaz — las aplicaciones que ya usan `defineConnectionProvider({ type: 'oauth', ... })` no necesitarán migrar.

> [accordion] defineConnectionProvider
>
> Declara cómo se obtienen las conexiones de tu aplicación
>
> Un proveedor de conexión describe el flujo de OAuth que tu aplicación necesita. Para un proveedor `WORKSPACE` (el predeterminado), un miembro 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. Consulta "Conexiones de espacio de trabajo o personales" para los proveedores `USER`.
>
> 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.
>
> ```ts src/connection-providers/linear-connection.ts theme={null}
> import { defineConnectionProvider } from 'twenty-sdk/define';
>
> export default defineConnectionProvider({
>   universalIdentifier: '9c7d1f5e-6a0b-4d44-be0c-3f8b5a9d4e6f',
>   name: 'linear',
>   displayName: 'Linear',
>   icon: 'IconBrandLinear',
>   // Optional: a logo bundled in your app's public/ folder, shown next to the
>   // provider in the app's General tab.
>   logo: 'public/linear-logomark.svg',
>   type: 'oauth',
>   scope: 'WORKSPACE',
>   oauth: {
>     authorizationEndpoint: 'https://linear.app/oauth/authorize',
>     tokenEndpoint: 'https://api.linear.app/oauth/token',
>     scopes: ['read', 'write'],
>     // These must match keys in `defineApplication.serverVariables` below.
>     clientIdVariable: 'LINEAR_CLIENT_ID',
>     clientSecretVariable: 'LINEAR_CLIENT_SECRET',
>     // Optional: defaults to 'json'. Some providers (Linear, Slack) want
>     // 'form-urlencoded' for the token request.
>     tokenRequestContentType: 'form-urlencoded',
>     // Optional: defaults to true. Disable only if the provider rejects PKCE.
>     usePkce: false,
>     // Optional: extra query params on the authorize URL.
>     // authorizationParams: { prompt: 'consent' },
>     // Optional: provider's RFC 7009 token revocation endpoint, called on disconnect.
>     // revokeEndpoint: 'https://example.com/oauth/revoke',
>   },
>   // Optional: a logic function in this app that returns a stable id for the
>   // upstream account, run before the tokens are saved. See "Identify the
>   // connected account".
>   // identifyAccountLogicFunction: { universalIdentifier: '2f1e0d9c-...-...' },
>   // Optional: a logic function in this app to run right after a connection is
>   // established. See "Run a logic function on connect".
>   // onConnectLogicFunction: { universalIdentifier: '3a2b1c0d-...-...' },
>   // Optional: a logic function in this app to run right after a connection is
>   // removed. See "Run a logic function on disconnect".
>   // onDisconnectLogicFunction: { universalIdentifier: '4d5e6f70-...-...' },
> });
> ```
>
> ```ts src/application.config.ts theme={null}
> import { defineApplication } from 'twenty-sdk/define';
>
> export default defineApplication({
>   universalIdentifier: '...',
>   displayName: 'Linear',
>   description: 'Connect Linear to Twenty.',
>   // OAuth client credentials live on the app registration (one OAuth app per
>   // Twenty server, configured by the admin) — not per-workspace. Declare them
>   // as serverVariables so the admin can fill them in once for all installs.
>   serverVariables: {
>     LINEAR_CLIENT_ID: {
>       description: 'OAuth client ID from your Linear OAuth application.',
>       isSecret: false,
>       isRequired: true,
>     },
>     LINEAR_CLIENT_SECRET: {
>       description: 'OAuth client secret from your Linear OAuth application.',
>       isSecret: true,
>       isRequired: true,
>     },
>   },
> });
> ```
>
> 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 General de la aplicación y en la lista de herramientas de IA.
> * `scope` determina quién se conecta: `'WORKSPACE'` (el predeterminado) para las conexiones compartidas con todo el espacio de trabajo, `'USER'` para las conexiones que cada miembro realiza por sí mismo. Consulta "Conexiones de espacio de trabajo o personales" a continuación.
> * `logo` es una ruta a un recurso incluido en la carpeta `public/` de tu aplicación, que se sirve a través de los recursos públicos de la aplicación. Cuando se omite, la pestaña General usa un marcador de posición creado a partir de `displayName`.
> * `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 ambas `serverVariables` estén completas, la pestaña General de la aplicación muestra un aviso de "requiere administrador del servidor" y el botón "Agregar conexión" está deshabilitado.
> * `type` es `'oauth'` (con un bloque `oauth`), `'oauth-discovery'` (con un bloque `oauthDiscovery`, consulta a continuación), `'custom'` (con un bloque `custom`, consulta "Flujos de conexión personalizados") o `'api-key'` (sin bloque, consulta "Conexiones de clave de API"). El discriminador es compatible con versiones futuras: los tipos futuros añadirán nuevos bloques de subconfiguración junto con estos.
>
> Para un servicio que publica su configuración de OAuth, como un servidor MCP remoto, declare `type: 'oauth-discovery'` con `oauthDiscovery: { resourceUrl }`, una URL HTTP o HTTPS. Al conectarse, Twenty detecta el servidor de autorización a partir del recurso (RFC 9728), se identifica con su documento de metadatos de cliente cuando el servidor lo admite; de lo contrario, registra un cliente dinámicamente y renueva los tokens como cualquier conexión OAuth. No se necesitan `serverVariables`. La detección se incluye con Twenty 2.59.0: si su aplicación declara un proveedor `oauth-discovery`, declare `"engines": { "twenty": ">=2.59.0" }` en su `package.json`.
>
> La URL de callback de OAuth que tu proveedor debe autorizar es:
>
> ```
> https://<your-twenty-server>/auth/apps/callback
> ```

> [accordion] Conexiones de clave de API
>
> Conecta servicios que se autentican con un token
>
> Muchos servicios (Front, Intercom, claves personales de Linear, ...) se autentican con una clave que el usuario copia de la configuración del servicio. Decláralos con `type: 'api-key'`; no hay ningún bloque de configuración:
>
> ```ts src/connection-providers/front-connection.ts theme={null}
> import { defineConnectionProvider } from 'twenty-sdk/define';
>
> export default defineConnectionProvider({
>   universalIdentifier: '1db544f6-dde4-4b42-a057-bd2c62bd3094',
>   name: 'front',
>   displayName: 'Front',
>   type: 'api-key',
>   scope: 'WORKSPACE',
>   identifyAccountLogicFunction: {
>     universalIdentifier: '16801854-29d2-4a90-9d56-333210647bcd',
>   },
>   onConnectLogicFunction: {
>     universalIdentifier: '53bc562a-2932-4452-bbda-4de8345a2cef',
>   },
> });
> ```
>
> **Añadir conexión** y **Reconectar** abren una página de configuración donde el miembro pega la clave. Twenty la almacena cifrada en la conexión, y `getConnection` la devuelve como `accessToken`, con `providerType: 'api-key'`. Twenty nunca la renueva ni la revoca: cuando el servicio la rechace, llama a `reportConnectionAuthFailure` para que se solicite al miembro que se vuelva a conectar con una nueva.
>
> Declara una `identifyAccountLogicFunction` (consulta "Identificar la cuenta conectada"). Se ejecuta con la clave pegada como `accessToken` antes de que se guarde nada, por lo que una llamada al endpoint "quién soy" del servicio comprueba la clave y asigna un nombre a la conexión. Si genera una excepción, la clave se rechaza y el miembro ve el error. Sin ella, se guarda cualquier clave no vacía y la conexión recibe el nombre del correo electrónico del miembro.
>
> Los proveedores de claves de API se incluyen con Twenty 2.59.0: declara `"engines": { "twenty": ">=2.59.0" }` en el `package.json` de tu aplicación.

> [accordion] Flujos de conexión personalizados
>
> Conecta servicios que no son proveedores de OAuth
>
> Algunos servicios conectan cuentas mediante su propio flujo en lugar de OAuth: Unipile, Plaid o Merge envían al usuario a una página alojada y luego informan de la cuenta conectada a una URL que les proporcionaste, a veces desde sus servidores en lugar de desde el navegador. Decláralos con `type: 'custom'` y dos funciones lógicas:
>
> ```ts src/connection-providers/linkedin-connection.ts theme={null}
> import { defineConnectionProvider } from 'twenty-sdk/define';
>
> export default defineConnectionProvider({
>   universalIdentifier: '5b0e6f3a-2c4d-4e8f-9a1b-7c6d5e4f3a2b',
>   name: 'linkedin',
>   displayName: 'LinkedIn',
>   type: 'custom',
>   scope: 'USER',
>   custom: {
>     authorizeLogicFunction: {
>       universalIdentifier: 'c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d',
>     },
>     callbackLogicFunction: {
>       universalIdentifier: 'd5b2f3c4-7e6a-4b8c-9d0e-1f2a3b4c5d6e',
>     },
>   },
>   onConnectLogicFunction: {
>     universalIdentifier: 'e6c3a4d5-8f7b-4c9d-0e1f-2a3b4c5d6e7f',
>   },
> });
> ```
>
> **Añadir conexión** y **Reconectar** funcionan igual que para OAuth. Twenty comprueba que el miembro pueda conectarse, firma un estado de corta duración para el intento y ejecuta `authorizeLogicFunction` con una `callbackUrl` que lo contiene. Devuelve a dónde enviar al usuario:
>
> ```ts src/logic-functions/handlers/linkedin-authorize-handler.ts theme={null}
> import { type AuthorizeConnectionPayload } from 'twenty-sdk/logic-function';
>
> export const linkedinAuthorizeHandler = async ({
>   callbackUrl,
> }: AuthorizeConnectionPayload) => {
>   const response = await fetch(
>     `${process.env.UNIPILE_DSN}/api/v1/hosted/accounts/link`,
>     {
>       method: 'POST',
>       headers: {
>         'X-API-KEY': process.env.UNIPILE_API_KEY ?? '',
>         'Content-Type': 'application/json',
>       },
>       body: JSON.stringify({
>         type: 'create',
>         providers: ['LINKEDIN'],
>         api_url: process.env.UNIPILE_DSN,
>         expiresOn: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
>         // The browser comes back here, and the account id is posted here.
>         success_redirect_url: callbackUrl,
>         failure_redirect_url: callbackUrl,
>         notify_url: callbackUrl,
>       }),
>     },
>   );
>
>   const { url } = await response.json();
>
>   return { authorizationUrl: url };
> };
> ```
>
> Pasa `callbackUrl` al servicio sin cambios. Twenty la acepta como una redirección del navegador (`GET`) y como una notificación del servidor (`POST`), y ejecuta `callbackLogicFunction` para cada solicitud con su método, parámetros de consulta (sin `state`), encabezados, cuerpo analizado y `rawBody` (los bytes exactos de la solicitud, `null` en `GET`). Devuelve la cuenta que demuestra la solicitud o `null` cuando no contiene ninguna; normalmente, el navegador regresa mientras el id de la cuenta se envía mediante una notificación:
>
> ```ts src/logic-functions/handlers/linkedin-callback-handler.ts theme={null}
> import { type ConnectionCallbackPayload } from 'twenty-sdk/logic-function';
>
> export const linkedinCallbackHandler = async ({
>   httpMethod,
>   body,
> }: ConnectionCallbackPayload) => {
>   if (httpMethod !== 'POST') {
>     return null;
>   }
>
>   const { account_id: accountId } = body as { account_id: string };
>
>   // Never trust the payload alone: confirm the account with the service.
>   const account = await fetchUnipileAccount(accountId);
>
>   return { externalAccountId: account.id, handle: account.name };
> };
> ```
>
> El estado firmado en `callbackUrl` solo demuestra que la solicitud contiene esa URL, no que el servicio la envió. Cuando el servicio firma sus notificaciones, verifica la firma sobre `rawBody` antes de confiar en el cuerpo. Los encabezados están en minúsculas, y `cookie`, `authorization` y `proxy-authorization` nunca se transmiten:
>
> ```ts src/logic-functions/handlers/hosted-callback-handler.ts theme={null}
> import { createHmac, timingSafeEqual } from 'node:crypto';
>
> import { type ConnectionCallbackPayload } from 'twenty-sdk/logic-function';
>
> export const hostedCallbackHandler = async ({
>   httpMethod,
>   headers,
>   rawBody,
> }: ConnectionCallbackPayload) => {
>   if (httpMethod !== 'POST' || rawBody === null) {
>     return null;
>   }
>
>   const expected = createHmac('sha256', process.env.WEBHOOK_SECRET ?? '')
>     .update(rawBody)
>     .digest();
>   const received = Buffer.from(headers['x-signature'] ?? '', 'hex');
>
>   if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
>     throw new Error('Invalid notification signature');
>   }
>
>   const { account_id: accountId } = JSON.parse(rawBody) as { account_id: string };
>
>   return { externalAccountId: accountId };
> };
> ```
>
> La devolución de llamada devuelve:
>
> | Campo | Descripción |
> | - | - |
> | `externalAccountId` | El id del servicio para la cuenta. Una devolución de llamada posterior para el mismo id y miembro actualiza esa conexión en lugar de añadir una segunda. |
> | `handle` | Etiqueta opcional mostrada para la conexión. De forma predeterminada, se usa el correo electrónico del miembro. |
> | `accessToken` | Token opcional por cuenta, almacenado cifrado y devuelto por `getConnection`. Omítelo cuando tu aplicación llame al servicio con su propia clave. |
>
> Ambas funciones se ejecutan mientras el miembro espera una redirección, por lo que su tiempo de espera está limitado a 10 segundos. Un fallo o una devolución no válida cancela la conexión: no se guarda nada y `onConnectLogicFunction` no se ejecuta. `onConnectLogicFunction` se ejecuta cuando se crea, reconecta o restaura una conexión, pero no de nuevo cuando el servicio informa de una cuenta que ya está conectada. El estado caduca después de una hora, por lo que se rechaza una notificación que llegue más tarde. Los servicios suelen reintentar las notificaciones: una repetición para una cuenta ya conectada actualiza esa conexión, por lo que es seguro devolver de nuevo la misma cuenta.
>
> Twenty no actualiza ni revoca las conexiones personalizadas. Libera lo que el servicio retiene para la cuenta en `onDisconnectLogicFunction`.
>
> El `type` de un proveedor, al igual que su `scope`, no puede cambiar una vez sincronizado: para mover un servicio entre `oauth`, `oauth-discovery`, `custom` y `api-key`, declara un proveedor nuevo con un `universalIdentifier` nuevo.
>
> Los proveedores personalizados se incluyen con Twenty 2.52.0.

> [accordion] Identifica la cuenta conectada
>
> Evita que una reconexión cambie silenciosamente las cuentas de origen
>
> Cuando un usuario hace clic en **Reconnect**, nada le impide autorizar una cuenta de origen distinta de aquella con la que se estableció la conexión: el espacio de trabajo B de Slack en lugar del espacio de trabajo A, otra organización de GitHub u otra cuenta de Google. Sin una forma de distinguirlas, Twenty sobrescribiría los tokens de A con los de B y todo lo que tu aplicación hubiera creado sobre esa conexión empezaría silenciosamente a comunicarse con B.
>
> Establece `identifyAccountLogicFunction` en una función de lógica de la misma aplicación que devuelva un identificador estable para la cuenta asociada al token recién emitido:
>
> ```ts src/connection-providers/slack-connection.ts theme={null}
> import { defineConnectionProvider } from 'twenty-sdk/define';
>
> import { SLACK_IDENTIFY_ACCOUNT_LOGIC_FUNCTION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
>
> export default defineConnectionProvider({
>   universalIdentifier: '...',
>   name: 'slack',
>   displayName: 'Slack',
>   type: 'oauth',
>   oauth: {
>     /* ... */
>   },
>   identifyAccountLogicFunction: {
>     universalIdentifier: SLACK_IDENTIFY_ACCOUNT_LOGIC_FUNCTION_UNIVERSAL_IDENTIFIER,
>   },
> });
> ```
>
> **Cuándo se ejecuta.** De forma sincrónica dentro de la devolución de llamada de OAuth, inmediatamente después de intercambiar el código de autorización por tokens y **antes** de guardar nada. El usuario está esperando la redirección, por lo que, cuando se instala o sincroniza la aplicación, Twenty limita el `timeoutSeconds` de la función a 10, independientemente de lo que declare el manifiesto; limítalo a una única solicitud al endpoint «quién soy» del proveedor. El hook de conexión, si lo hay, se sigue ejecutando después, una vez guardada la conexión.
>
> **Carga útil.** El controlador recibe el token de acceso provisional. Aún no se ha guardado, por lo que `getConnection` no puede devolverlo; úsalo directamente y no lo registres.
>
> ```ts theme={null}
> type IdentifyAccountPayload = {
>   connectionProviderId: string;
>   connectionProviderName: string; // e.g. 'slack'
>   accessToken: string;
> };
> ```
>
> **Resultado.** Devuelve el id de la cuenta y, opcionalmente, un identificador para mostrar:
>
> ```ts theme={null}
> type IdentifyAccountResult = {
>   externalAccountId: string | null; // non-empty, at most 512 characters; null opts out
>   handle?: string; // non-empty when present
> };
> ```
>
> * `externalAccountId` debe ser estable durante toda la vida de la cuenta ascendente (un id de equipo, un id de organización o un id de usuario), nunca un nombre que el usuario pueda cambiar. Twenty lo recorta y lo almacena en la conexión durante la primera conexión.
> * `handle`, cuando se devuelve, sustituye al handle que Twenty determinaría de otro modo (el correo electrónico del `id_token` de OIDC o el correo electrónico del usuario que se conecta). Devuelve algo que un usuario reconozca, como el nombre del espacio de trabajo de Slack.
> * Devuelve `{ externalAccountId: null }` cuando el proveedor no tiene un id estable que ofrecer. Twenty se comporta entonces como si no se hubiera declarado ninguna función de identificación: no se almacena ningún id, una reconexión borra cualquier id almacenado anteriormente y no se comprueban las reconexiones. Un `null` sin más o la ausencia de un retorno se tratan como un error, por lo que un controlador que olvide devolver algo no puede desactivar silenciosamente la comprobación.
> * Si la función lanza una excepción, agota el tiempo de espera o devuelve cualquier otra cosa, la conexión **no** se guarda y el usuario vuelve a la página de configuración con un error. Lanza una excepción solo cuando realmente no puedas identificar la cuenta.
>
> **Rechazo de reconexión.** Durante una reconexión, Twenty compara el `externalAccountId` devuelto con el almacenado en la conexión. Si difieren, se rechaza la devolución de llamada antes de que se escriba nada: los tokens, el identificador y el ámbito existentes permanecen como estaban, el hook de conexión no se ejecuta y el usuario ve qué cuenta autorizó y a cuál pertenece la conexión. Las conexiones creadas antes de que tu aplicación declarara la función aún no tienen un id almacenado; su próxima reconexión lo almacenará.
>
> Twenty no elimina duplicados según `externalAccountId`: conectar dos veces la misma cuenta upstream mediante **Agregar conexión** crea dos conexiones. El id se expone en `listConnections` y `getConnection`, por lo que una aplicación que quiera una conexión por cuenta ascendente puede detectar los duplicados por sí misma (por ejemplo, en su hook al conectar).
>
> **Cómo escribir la función.** La mayoría de los proveedores exponen un único endpoint que describe el token actual. Para Slack es `auth.test`, que devuelve el espacio de trabajo (`team_id`, `team`) y el usuario detrás del token:
>
> ```ts src/logic-functions/slack-identify-account.ts theme={null}
> import { defineLogicFunction } from 'twenty-sdk/define';
> import type {
>   IdentifyAccountPayload,
>   IdentifyAccountResult,
> } from 'twenty-sdk/logic-function';
>
> import { SLACK_IDENTIFY_ACCOUNT_LOGIC_FUNCTION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
>
> export default defineLogicFunction({
>   universalIdentifier: SLACK_IDENTIFY_ACCOUNT_LOGIC_FUNCTION_UNIVERSAL_IDENTIFIER,
>   name: 'slack-identify-account',
>   timeoutSeconds: 10,
>   handler: async ({
>     accessToken,
>   }: IdentifyAccountPayload): Promise<IdentifyAccountResult> => {
>     const response = await fetch('https://slack.com/api/auth.test', {
>       method: 'POST',
>       headers: { Authorization: `Bearer ${accessToken}` },
>     });
>     const { ok, error, team_id, team } = await response.json();
>
>     if (!ok) {
>       throw new Error(`auth.test failed: ${error}`);
>     }
>
>     return { externalAccountId: team_id, handle: team };
>   },
> });
> ```
>
> Otros proveedores siguen el mismo patrón, tanto si su endpoint «quién soy» es REST como GraphQL. Lanza un error cuando el proveedor rechace el token y devuelve el id como una cadena: convierte los id numéricos, como los id de usuario de GitHub, con `String(id)`.
>
> La identificación está disponible a partir de Twenty 2.48.0. Si tu aplicación depende de ella, declara `"engines": { "twenty": ">=2.48.0" }` en su `package.json`.

> [accordion] Ejecutar una función de lógica al conectar
>
> Reaccionar en el momento en que se establece una conexión
>
> Algunos proveedores te entregan datos en el momento de la conexión que necesitas conservar antes de que la conexión sea utilizable: el ejemplo clásico es Slack, donde la respuesta de OAuth identifica el `team_id` del espacio de trabajo con el que se asociarán los eventos entrantes. Establece `onConnectLogicFunction` para que haga referencia a una función de lógica en la misma aplicación (por su `universalIdentifier`), y se ejecutará justo después de que se cree el `ConnectedAccount`.
>
> ```ts src/connection-providers/slack-connection.ts theme={null}
> export default defineConnectionProvider({
>   universalIdentifier: '...',
>   name: 'slack',
>   displayName: 'Slack',
>   type: 'oauth',
>   oauth: {
>     /* ... */
>   },
>   // Runs claimSlackTeam after every successful Slack connection.
>   onConnectLogicFunction: {
>     universalIdentifier: '3a2b1c0d-1111-4222-8333-444455556666',
>   },
> });
> ```
>
> El hook se ejecuta **de forma asíncrona en el espacio de trabajo que se está conectando** (se pone en cola, no se espera su finalización), por lo que un hook lento o con fallos nunca bloquea ni interrumpe el callback de OAuth; hazlo idempotente y haz que gestione sus propios reintentos. El controlador recibe:
>
> ```ts theme={null}
> type OnConnectPayload = {
>   connectionProviderId: string;
>   connectionProviderName: string; // e.g. 'slack'
>   connectedAccountId: string;
> };
> ```
>
> A partir de ahí, usa `getConnection(connectedAccountId)` para leer el token de acceso reciente y llamar a la API del proveedor (por ejemplo, Slack `auth.test`) o para conservar un mapeo con el [almacenamiento de pares clave-valor](https://docs.twenty.com/es/developers/extend/apps/logic/key-value-store.md).

> [accordion] Ejecutar una función de lógica al desconectar
>
> Limpieza cuando se desconecta o se elimina una conexión.
>
> Todo lo que una aplicación reclame en el momento de la conexión debe liberarse cuando la conexión se termina. Una integración de Slack que reclame un `team_id` al conectarse, por ejemplo, debe liberar esa reserva para que otro espacio de trabajo pueda conectar ese mismo espacio de trabajo de Slack. Configura `onDisconnectLogicFunction` para que haga referencia a una función de lógica en la misma aplicación; se ejecuta cuando se desconecta la conexión y de nuevo cuando se elimina.
>
> ```ts src/connection-providers/slack-connection.ts theme={null}
> export default defineConnectionProvider({
>   universalIdentifier: '...',
>   name: 'slack',
>   displayName: 'Slack',
>   type: 'oauth',
>   oauth: {
>     /* ... */
>   },
>   // Runs releaseSlackTeam after every Slack disconnection.
>   onDisconnectLogicFunction: {
>     universalIdentifier: '4470aba8-5ff5-4800-88db-2a427cd8677c',
>   },
> });
> ```
>
> A diferencia del gancho de conexión, se ejecuta **en línea en el espacio de trabajo que se está desconectando**, sin reintentos: se captura un error y la desconexión o eliminación se completa de todos modos. El controlador recibe la misma estructura de payload:
>
> ```ts theme={null}
> type OnDisconnectPayload = {
>   connectionProviderId: string;
>   connectionProviderName: string; // e.g. 'slack'
>   connectedAccountId: string;
> };
> ```
>
> Al desconectarse, `ConnectedAccount` y su token siguen presentes, por lo que `getConnection(connectedAccountId)` se resuelve y el controlador puede liberar todo lo que registró de forma remota. Al eliminar, es posible que las credenciales ya no estén disponibles (un miembro puede eliminar una conexión que desconectó anteriormente), así que haz que el controlador sea idempotente y conserva el estado que necesita (un `team_id`, un ID de suscripción externa) en el [almacén de clave-valor](https://docs.twenty.com/es/developers/extend/apps/logic/key-value-store.md), escrito en el momento de la conexión y con la clave `connectedAccountId`. Que sea breve: se ejecuta dentro de la solicitud, por lo que su `timeoutSeconds` es el límite máximo de duración de esa solicitud.
>
> El hook se dispara cuando una conexión se desconecta o se elimina por sí sola. Desinstalar la app elimina sus conexiones mediante una cascada de base de datos, por lo que el hook no se ejecuta en ese caso. Declara una `uninstallLogicFunction` en `defineApplication` para esa ruta: se ejecuta antes de que se eliminen los metadatos de la app, por lo que todavía puede llamar a `listConnections` y limpiar lo que quede.

> [accordion] listConnections / getConnection
>
> Usa conexiones desde una función de lógica
>
> 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.
>
> ```ts src/logic-functions/handlers/create-linear-issue-handler.ts theme={null}
> import { listConnections } from 'twenty-sdk/logic-function';
>
> export const createLinearIssueHandler = async (input: {
>   teamId?: string;
>   title?: string;
> }) => {
>   if (!input.teamId || !input.title) {
>     return { success: false, error: 'teamId and title are required' };
>   }
>
>   const connections = await listConnections({ providerName: 'linear' });
>
>   // Workspace-shared credentials win when present; fall back to the first
>   // personal one. For HTTP-route triggers you typically pick the
>   // request user's connection via event.userWorkspaceId instead.
>   const connection =
>     connections.find((c) => c.scope === 'WORKSPACE') ?? connections[0];
>
>   if (!connection) {
>     return {
>       success: false,
>       error:
>         'Linear is not connected. Open the app settings and click "Add connection".',
>     };
>   }
>
>   // Use connection.accessToken to call the third-party API.
>   const response = await fetch('https://api.linear.app/graphql', {
>     method: 'POST',
>     headers: {
>       Authorization: `Bearer ${connection.accessToken}`,
>       'Content-Type': 'application/json',
>     },
>     body: JSON.stringify({
>       query: `mutation { issueCreate(input: { teamId: "${input.teamId}", title: "${input.title}" }) { success } }`,
>     }),
>   });
>
>   return { success: response.ok };
> };
> ```
>
> Cada conexión tiene:
>
> | Campo | Descripción |
> | - | - |
> | `id` | ID de fila único; pásalo a `getConnection(id)` para volver a obtener una sola conexión |
> | `scope` | `'USER'` (pertenece al miembro que se conecta) o `'WORKSPACE'` (compartida con todos los miembros) |
> | `visibility` | En desuso: `scope` en minúsculas (`'user'` o `'workspace'`). Usa `scope` en su lugar |
> | `scopes` | Permisos de OAuth concedidos por el proveedor de origen (distintos de `scope` — no están relacionados) |
> | `userWorkspaceId` | El id de userWorkspace del propietario — útil para elegir "la conexión del usuario de la solicitud" en activadores de rutas HTTP |
> | `workspaceMemberId` | El id de miembro del espacio de trabajo del propietario, o `null` si desde entonces ha abandonado el espacio de trabajo |
> | `providerType` | `'oauth'`, `'custom'` o `'api-key'`, el tipo del proveedor de conexión (las conexiones `oauth-discovery` informan de `'oauth'`). Compruébalo para restringir `accessToken` |
> | `accessToken` | Token de acceso OAuth actual (se actualiza automáticamente si caduca), siempre establecido cuando `providerType` es `'oauth'`. Para `'custom'`, `null` a menos que la devolución de llamada haya devuelto uno. Para `'api-key'`, la clave que introdujo el miembro |
> | `nombre` | El nombre para mostrar de la conexión (derivado automáticamente en el callback de OAuth, el usuario puede cambiarlo) |
> | `identificador` | La etiqueta de la cuenta upstream conectada, actualizada en cada reconexión: el `handle` devuelto por la función de identificación cuando lo hay; de lo contrario, el correo electrónico del `id_token` de OIDC devuelto durante el intercambio de tokens, con el correo electrónico del usuario de Twenty que se conecta como alternativa |
> | `externalAccountId` | Id estable de la cuenta ascendente devuelto por la función de identificación, o `null` cuando el proveedor no declara ninguno o la conexión es anterior a ella. No es único: úsalo para eliminar duplicados de conexiones por tu cuenta |
> | `authFailedAt` | Se establece cuando la actualización más reciente falló o cuando la aplicación informó que la credencial ya no es válida mediante `reportConnectionAuthFailure`; el usuario debe volver a conectarse |
> | `authFailedReason` | Explicación legible para humanos de `authFailedAt`, cuando quien informó proporcionó una; se muestra en la página de detalles de la conexión en la configuración |
>
> 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.

> [accordion] reportConnectionAuthFailure
>
> Indica a la plataforma que una credencial ya no es válida
>
> La plataforma establece `authFailedAt` por sí sola únicamente cuando falla una actualización de OAuth. Los proveedores cuyos tokens nunca se actualizan (por ejemplo, un token de bot de Slack) fallan únicamente en el momento de la llamada dentro de tus controladores, por lo que la fila de conexión en la configuración seguiría mostrando **Conectada** mientras falla cada llamada. Cuando tu código recibe un rechazo de autenticación definitivo, infórmalo:
>
> ```ts theme={null}
> import { reportConnectionAuthFailure } from 'twenty-sdk/logic-function';
>
> await reportConnectionAuthFailure({
>   connectionId: connection.id,
>   reason:
>     'Slack rejected the stored token (invalid_auth). Reconnect to restore the integration.',
> });
> ```
>
> Esto establece `authFailedAt` y el motivo opcional en la conexión. La fila de configuración cambia a **Se necesita reconectar** con un botón Reconectar, la página de detalles de la conexión muestra el motivo y `getConnection` comienza a lanzar `AppConnectionAuthFailedError` para esa fila. La marca y el motivo se borran automáticamente cuando el usuario se reconecta. Se rechaza un `reason` de más de 1000 caracteres, así que trunca las cargas útiles del proveedor antes de pasarlas.
>
> Informa únicamente los fallos que una reconexión realmente corregiría (un rechazo de la clase `invalid_auth` del proveedor), nunca los errores transitorios de red. Una aplicación solo puede informar de sus propias conexiones, y un usuario de solicitud solo puede informar de sus propias credenciales personales.
>
> La mutación detrás de este asistente se incluye con Twenty 2.40.0, por lo que llamarla en un servidor anterior falla. Si tu aplicación la usa, declara la dependencia en tu `package.json`: `"engines": { "twenty": ">=2.40.0" }`.

> [accordion] Conexiones de espacio de trabajo o personales
>
> Elige quién se conecta con el ámbito del proveedor
>
> Cada conexión tiene uno de dos ámbitos:
>
> * **Compartida en el espacio de trabajo** (`'WORKSPACE'`) — 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.
> * **Solo para mí** (`'USER'`) — la credencial pertenece al miembro que se conecta. En las ejecuciones realizadas en nombre de un miembro (activador de ruta HTTP con `isAuthRequired: true`), `listConnections` devuelve las conexiones compartidas más las propias de ese miembro, y `findConnectionForRequest` selecciona la conexión personal del miembro, recurriendo a una compartida cuando no tiene ninguna. En las ejecuciones sin un usuario de solicitud (por ejemplo, activadores cron), `listConnections` devuelve todas las conexiones, incluidas las personales de cada miembro.
>
> El `scope` del proveedor determina cuál reciben sus nuevas conexiones:
>
> * `scope: 'WORKSPACE'` (el predeterminado) — la aplicación funciona con conexiones compartidas con el espacio de trabajo. **Agregar conexión** en la configuración del espacio de trabajo de la aplicación crea una conexión compartida con el espacio de trabajo.
>
> * `scope: 'USER'` — cada miembro conecta su propia cuenta, creando conexiones personales. Los miembros las añaden, reconectan y eliminan desde la página de la aplicación en **Configuración > Usuario > Preferencias de aplicaciones**, lo que requiere el permiso Aplicaciones de usuario. La configuración del espacio de trabajo de la aplicación no tiene un botón **Agregar conexión** para un proveedor `USER`.
>
> > [!NOTE]
> >
> > **Preferencias de apps** aún no está habilitado en todos los espacios de trabajo: donde no lo está,
> > los miembros no tienen dónde agregar una conexión `USER`, así que no dependas de una para
> > una función que todos los espacios de trabajo necesitan ahora.
>
> Un proveedor tiene exactamente un ámbito. Si tu aplicación necesita tanto una credencial compartida como una por miembro para el mismo servicio (por ejemplo, un token de bot y la cuenta propia de cada miembro), declara dos proveedores.
>
> Una conexión siempre tiene el ámbito de su proveedor, y el ámbito de un proveedor forma parte de su identidad: una versión posterior no puede cambiar el `scope` de un proveedor existente, y la actualización se rechaza si lo intenta. Para mover un servicio de un ámbito a otro, declare un proveedor nuevo con un `universalIdentifier` nuevo y elimine el anterior. La actualización elimina entonces el proveedor anterior y todas las conexiones realizadas con él mediante la ruta de desconexión habitual (`onDisconnectLogicFunction`, revocación de tokens, limpieza de canales), y los miembros se conectan de nuevo mediante el proveedor nuevo.
>
> Para añadir o reconectar una conexión **Solo para mí** se requiere el permiso Aplicaciones de usuario, y para añadir o reconectar una conexión **Compartida en el espacio de trabajo** se requiere el permiso Aplicaciones del espacio de trabajo.
>
> Usa la conexión adecuada para cada controlador:
>
> ```ts theme={null}
> // HTTP-route trigger — prefer the request user's own connection.
> const conn =
>   connections.find((c) => c.userWorkspaceId === event.userWorkspaceId) ??
>   connections.find((c) => c.scope === 'WORKSPACE');
>
> // Cron trigger — no request user; only shared credentials are sensible.
> const conn = connections.find((c) => c.scope === 'WORKSPACE');
> ```
>
> 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.
>
> El ámbito del proveedor se incluye en Twenty 2.49.0. Si tu aplicación declara `scope`, declara `"engines": { "twenty": ">=2.49.0" }` en su `package.json`. En la misma versión, el `scope` de una conexión reemplaza su `visibility`, que sigue disponible como un alias en minúsculas en desuso. `listConnections` y `getConnection` de `twenty-sdk` 2.49.0 leen `scope`, por lo que las aplicaciones creadas con él necesitan un servidor 2.49.0.

> [accordion] Configuración única del proveedor
>
> Registra tu aplicación OAuth con el servicio de terceros
>
> 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](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 a proveedores `WORKSPACE` desde la sección **Conexiones** de cada aplicación.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.