API de Conexiones

Lista las conexiones del proyecto, las más recientes primero, como máximo 200 por página; devuelva next_cursor como after para la siguiente.

Una conexión es el acceso reutilizable del proyecto a Microsoft o Google para las fuentes que se ejecutan sin supervisión: una fuente de datos microsoft365 o google_calendar, una conexión de Power BI y una cuenta de sincronización de medios de SharePoint nombran una en config.connection_id en lugar de llevar credenciales propias (docs/connections.md).

Un secreto, una clave o un token de actualización nunca se devuelve: secret indica si hay uno guardado y una pista que no es secreta. Una lectura nunca incluye un enlace de consentimiento.

Crea una conexión con Microsoft (provider microsoft) o Google (provider google). El modo own_app es la aplicación propia del cliente: para Microsoft, config.tenant_id (el ID de directorio o el dominio principal; common, organizations y consumers se rechazan), config.client_id y secret (el valor de uno de los secretos de cliente de la aplicación); para Google, secret es el archivo de clave JSON de la cuenta de servicio.

El secreto se sella y nunca se devuelve. El modo screenrig_app usa la aplicación propia de screenRIG y no admite config ni secret: la conexión se crea en estado pending_consent y la respuesta lleva consent_url, un enlace de un solo uso (válido hasta consent_expires_at) para la persona que lo completa.

Para Microsoft es un administrador de Microsoft 365, que da su consentimiento a la aplicación de screenRIG para el tenant; el navegador inicia entonces sesión en el tenant que Microsoft nombra, de modo que la conexión registra el tenant confirmado, nunca uno que un callback solo afirme.

Para Google es el titular de la cuenta, que concede acceso de solo lectura a los calendarios que la cuenta puede ver; screenRIG guarda sellado el token de actualización y la dirección de la cuenta. El enlace es una credencial de un solo consentimiento: envíelo solo a esa persona.

Un servidor sin la aplicación de screenRIG para el proveedor responde 409 connection_app_not_configured, y las conexiones own_app siguen funcionando. Una organización tiene como máximo 50 conexiones en todos sus proyectos (connection_limit_reached). Añade connection.created.

Un reintento exacto con la misma Idempotency-Key devuelve la misma conexión (un reintento de screenrig_app recibe un enlace de consentimiento nuevo, que sustituye al primero).

Una conexión, con su estado, su último error y su última prueba.

Cambia el nombre de una conexión o, en modo own_app, sus credenciales: config.tenant_id y config.client_id (Microsoft) o secret (un secreto enviado sustituye al sellado; uno omitido se conserva). Una conexión en modo screenrig_app solo puede cambiar de nombre: vuelva a conectarla (POST /api/connections/{id}/connect) para cambiar quién dio el consentimiento.

Un cambio de las credenciales devuelve la conexión a ready, borra last_error y last_test y retira todos los tokens emitidos para las credenciales anteriores. Añade connection.updated. If-Match protege la revisión.

Elimina una conexión por la que no lee nada. Mientras una fuente de datos, una conexión de Power BI o una cuenta de sincronización de medios la usa, la respuesta es resource_conflict, que los nombra (used_by lista su tipo y su ID).

Eliminar no pone fin a lo que queda del lado del proveedor: un tenant de Microsoft 365 conserva la aplicación de screenRIG hasta que su administrador la quite, y una cuenta de Google conserva su concesión hasta que su titular la revoque. Añade connection.deleted. If-Match protege la revisión.

Inicia sesión con la conexión y guarda la respuesta como last_test.

Para Microsoft las comprobaciones son credentials (Microsoft emitió un token de aplicación para el tenant) y permissions (cuáles de Calendars.Read, Sites.Selected, Files.Read.All, Sites.Read.All y Place.Read.All lleva el token de la aplicación; una aplicación que no tiene ninguno no supera la comprobación, y Sites.Selected solo es una advertencia porque cada sitio de SharePoint necesita una concesión).

Para Google la comprobación es credentials: Google aceptó la cuenta de servicio o el token de actualización de la cuenta que concedió el acceso, y la respuesta nombra la cuenta a la que deben ser visibles los calendarios. Un rechazo es una comprobación fallida y pasa la conexión a error con last_error; un éxito la devuelve a ready.

No juzga el uso compartido de un calendario, una política de acceso a un buzón ni una concesión de sitio, algo que una fuente o una sincronización demuestra al ejecutarse. Como máximo 30 por minuto por organización.

Genera un nuevo enlace de consentimiento de un solo uso (consent_url, válido hasta consent_expires_at) para una conexión en modo screenrig_app, para enviarlo a la persona que lo completa: el administrador de Microsoft 365 o el titular de la cuenta de Google. Sustituye cualquier enlace anterior.

Una conexión que funciona se queda como está hasta que se completa el nuevo consentimiento, así que esto también renueva una que pasó a error (consentimiento retirado, acceso revocado) o la mueve a otro tenant o cuenta. El enlace es una credencial del consentimiento: envíelo solo a esa persona.

Cuando la persona termina, el navegador vuelve a GET /oauth/connections/{provider}/callback y se envía a la página de la conexión en el panel, que lee status y last_error. Una conexión en modo own_app no tiene paso de consentimiento (409 resource_conflict); un servidor sin la aplicación de screenRIG para el proveedor responde 409 connection_app_not_configured.

A dónde envía Microsoft el navegador de un administrador de Microsoft 365 después de la página de consentimiento de administrador (y de nuevo después del paso de inicio de sesión que la sigue) para una conexión en modo screenrig_app.

No lleva ninguna credencial: el state firmado de la consulta es la única autoridad, se verifica antes de leer nada de lo que nombra y solo se respeta mientras sea el consentimiento pendiente de la conexión.

El primer retorno nombra un tenant, que no está autenticado: la respuesta es una redirección al inicio de sesión de ese tenant, cuyo código se canjea con el secreto de la aplicación y un verificador PKCE que solo este servidor puede derivar, y el tenant que lleva el token de ID es el que registra la conexión después de que un token de credenciales de cliente demuestre que la aplicación tiene allí sus permisos.

Cada resultado posterior a un state verificado redirige a la página de la conexión en el panel (/dashboard/connections/{id}?consent=connected o ?consent=failed), que lee status y last_error; el texto del error se construye a partir de frases fijas y de la propia respuesta de error de Microsoft (su código AADSTS), nunca a partir de lo que llevaba la consulta del callback.

Un state desconocido, caducado, usado, sustituido o de una conexión eliminada muestra una página que no nombra nada. Solo responde en el host de la API bajo el que están registrados los callbacks.

A dónde envía Google el navegador del titular de la cuenta después de la página de consentimiento para una conexión en modo screenrig_app.

No lleva ninguna credencial: el state firmado de la consulta es la única autoridad, se verifica antes de leer nada de lo que nombra y solo se respeta mientras sea el consentimiento pendiente de la conexión. screenRIG canjea el código con el secreto de la aplicación y un verificador PKCE que solo este servidor puede derivar, exige que se haya concedido el ámbito de calendario (una persona puede desmarcarlo en la página de consentimiento) y un token de actualización, lee la cuenta que concedió el acceso del token de ID que Google devolvió en esa llamada, sella el token de actualización y añade connection.connected.

Cada resultado posterior a un state verificado redirige a la página de la conexión en el panel (/dashboard/connections/{id}?consent=connected o ?consent=failed), que lee status y last_error. Un state desconocido, caducado, usado, sustituido o de una conexión eliminada muestra una página que no nombra nada.

Solo responde en el host de la API bajo el que están registrados los callbacks.