Apps conectadas (OAuth)

Cuando lo que estás construyendo trabaja para una persona, lo que quieres no es una clave del espacio sino que esa persona te autorice. El resultado es un token que ve lo que ella ve. Para una integración sin persona detrás, usa una clave de API en su lugar.

La regla que gobierna todo

Una conexión nunca puede hacer más que la persona que la autorizó. Se aplica en dos momentos, no en uno:

1. Al autorizar. La pantalla de consentimiento solo ofrece los permisos que esa persona podría conceder. Si no tiene puesto en Swarm, los permisos de Swarm no aparecen para marcar.
2. En cada llamada. Cada aplicación vuelve a comprobar el token contra el rol y las membresías que esa persona tiene hoy. El token no las esquiva.

Por eso, si mañana esa persona pierde un acceso, la conexión también lo pierde, sin que nadie tenga que acordarse de revocarla.

El flujo

Es OAuth 2.1 estándar, código de autorización con PKCE. El resultado autoriza el acceso a datos; no inicia sesión en tu producto, así que no hay id_token, ni /userinfo, ni nonce.

Un cliente que hable el protocolo no necesita nada de esto escrito: pide el endpoint de MCP sin credencial, recibe un 401 con WWW-Authenticate apuntando a los metadatos, y desde ahí encuentra todo solo.

Lo que hay que saber antes de escribir código

• PKCE con S256 es obligatorio, y es la única prueba de identidad del cliente. plain no se ofrece.
• No hay secretos de cliente. Todos los clientes son públicos. No busques dónde pegar uno porque no existe.
• Tu client_id puede ser una URL. Si empieza por https://, Eel la lee como documento de metadatos y la recuerda durante una hora. Si prefieres registrarte, hay registro dinámico en POST /api/oauth/register.
• El redirect_uri se compara carácter por carácter. La única excepción es loopback, donde el puerto queda libre porque una app de escritorio no puede saber de antemano cuál le va a tocar. 127.0.0.1, [::1] y localhost cuentan todos como loopback.
• Toda respuesta de autorización trae iss, también las de error. Un cliente conforme debe rechazar la que no lo traiga.

Duraciones

Cada refresco emite un par nuevo y consume el anterior. Reusar un refresco ya consumido revoca la familia entera. Refresca desde un solo hilo: si tu cliente refresca dos veces en paralelo, el resultado es una desconexión, y eso es preferible a que alguien más se quede con el acceso en silencio. El par nuevo siempre hereda los permisos de la familia: refrescar no permite reducirlos.

No hay endpoint de introspección. Un token no se puede consultar de antemano: se usa y se ve si responde.

Una conexión puede autorizar varios espacios

La pantalla de consentimiento ofrece una casilla por cada espacio que puedas conceder, no una sola opción: puedes marcar varios a la vez. El primero que marques queda como el espacio por defecto del token; los demás quedan igual de autorizados, cada uno con sus propios permisos, recortados a lo que tienes en ese espacio en concreto. Por eso una misma conexión puede ser de lectura y escritura en un espacio y de solo lectura en otro.

Una herramienta MCP puede pedir actuar en cualquiera de los espacios autorizados con el argumento workspace (id o slug); sin él, actúa en el espacio por defecto. La URL del conector también acepta ?workspace=<id> para preseleccionar una casilla. Para la versión de este mismo procedimiento contada desde el lado del asistente, ver Espacios de trabajo en MCP y Conectar un asistente.

Cambiar los espacios sin reconectar

Ampliar o quitar espacios de una conexión ya autorizada se hace en Nest, en Apps conectadas, y no exige volver a autorizar nada desde el lado del asistente: el token sigue siendo el mismo, con el mismo client_id y la misma cadena de refresco. El cambio se aplica dentro de la misma ventana de 60 segundos que rige la revocación.

Quitar el espacio por defecto asciende al más antiguo de los que queden. Quitar el último equivale a revocar la conexión entera.

Ampliar los permisos sin reconectar

Una conexión lleva los permisos que se firmaron en su consentimiento. Un permiso que Eel publicó después no le llega solo, y sus herramientas no aparecen en el catálogo del asistente.

La persona que autorizó la conexión los aprueba en Nest, en Apps conectadas. Ese aprobado alcanza solo las aplicaciones que la conexión ya usa, recortado a lo que esa persona puede conceder hoy en cada espacio. Una conexión sin ningún permiso de escritura en una aplicación solo recibe lecturas nuevas de ella.

El token es el mismo y la cadena de refresco también: el cambio se aplica dentro de la misma ventana de 60 segundos. El asistente muestra las herramientas nuevas la próxima vez que se conecta. Si quieres verlas ya, desactiva y vuelve a activar el conector: no hace falta autorizarlo de nuevo.

Cuándo sí hace falta reconectar

Solo en estos casos:

• La primera conexión.
• Una conexión revocada del todo.
• Una cadena de refresco que ya expiró.
• Llegar a una aplicación que la conexión nunca ha tocado.

Achicar permisos, cambiar de espacios y ampliar permisos dentro de las aplicaciones que la conexión ya usa nunca lo exigen.

Revocar

Dos lugares, dos alcances:

• Cada persona, en Nest → Tu cuenta → Apps conectadas, revoca las suyas enteras, en todos los espacios donde estuvieran autorizadas.
• Un administrador, en Espacio de trabajo → Apps conectadas, ve las conexiones autorizadas en SU espacio y puede cortar cualquiera, pero solo ahí: si esa misma conexión también está autorizada en otro espacio, sigue viva ahí. Solo muere del todo cuando el espacio que corta era el último que le quedaba.

El corte tarda hasta 60 segundos en propagarse.