API Connexions

Liste les connexions du projet, les plus récentes d’abord, au plus 200 par page ; renvoyez next_cursor comme after pour la suivante.

Une connexion est l’accès réutilisable du projet à Microsoft ou à Google pour les sources qui s’exécutent sans surveillance : une source de données microsoft365 ou google_calendar, une connexion Power BI et un compte de synchronisation de médias SharePoint en nomment une dans config.connection_id au lieu de porter leurs propres identifiants (docs/connections.md).

Un secret, une clé ou un jeton d’actualisation n’est jamais renvoyé : secret indique si l’un d’eux est conservé et un indice qui n’est pas secret. Une lecture ne porte jamais de lien de consentement.

Crée une connexion à Microsoft (provider microsoft) ou à Google (provider google). Le mode own_app est l’application propre du client : pour Microsoft, config.tenant_id (l’ID de répertoire ou le domaine principal ; common, organizations et consumers sont refusés), config.client_id et secret (la valeur de l’un des secrets client de l’application) ; pour Google, secret est le fichier de clé JSON du compte de service.

Le secret est scellé et jamais renvoyé. Le mode screenrig_app utilise l’application propre de screenRIG et n’accepte ni config ni secret : la connexion est créée à l’état pending_consent et la réponse porte consent_url, un lien à usage unique (valide jusqu’à consent_expires_at) pour la personne qui le complète.

Pour Microsoft, c’est un administrateur Microsoft 365, qui consent à l’application de screenRIG pour le locataire ; le navigateur ouvre ensuite une session auprès du locataire que Microsoft nomme, de sorte que la connexion enregistre le locataire confirmé, jamais un locataire qu’un callback ne ferait que prétendre.

Pour Google, c’est le titulaire du compte, qui accorde un accès en lecture seule aux calendriers que le compte peut voir ; screenRIG conserve le jeton d’actualisation scellé et l’adresse du compte. Le lien est un identifiant d’un seul consentement : ne l’envoyez qu’à cette personne.

Un serveur sans l’application de screenRIG pour le fournisseur répond 409 connection_app_not_configured, et les connexions own_app continuent de fonctionner. Une organisation a au plus 50 connexions dans l’ensemble de ses projets (connection_limit_reached). Ajoute connection.created.

Une nouvelle tentative identique avec la même Idempotency-Key renvoie la même connexion (une nouvelle tentative screenrig_app reçoit un nouveau lien de consentement, qui remplace le premier).

Une connexion, avec son statut, sa dernière erreur et son dernier test.

Modifie le nom d’une connexion ou, en mode own_app, ses identifiants : config.tenant_id et config.client_id (Microsoft) ou secret (un secret envoyé remplace celui qui est scellé ; un secret omis est conservé). Une connexion en mode screenrig_app ne peut qu’être renommée : reconnectez-la (POST /api/connections/{id}/connect) pour changer la personne qui a donné son consentement.

Une modification des identifiants ramène la connexion à ready, efface last_error et last_test et retire tous les jetons émis pour les anciens identifiants. Ajoute connection.updated. If-Match protège la révision.

Supprime une connexion par laquelle rien ne lit. Tant qu’une source de données, une connexion Power BI ou un compte de synchronisation de médias en utilise une, la réponse est resource_conflict, qui les nomme (used_by liste leur type et leur ID).

La suppression ne met pas fin au côté du fournisseur : un locataire Microsoft 365 conserve l’application de screenRIG jusqu’à ce que son administrateur la retire, et un compte Google conserve son autorisation jusqu’à ce que son titulaire la révoque. Ajoute connection.deleted. If-Match protège la révision.

Ouvre une session avec la connexion et enregistre la réponse comme last_test.

Pour Microsoft, les vérifications sont credentials (Microsoft a émis un jeton d’application pour le locataire) et permissions (lesquelles parmi Calendars.Read, Sites.Selected, Files.Read.All, Sites.Read.All et Place.Read.All le jeton de l’application porte ; une application qui n’en détient aucune échoue à la vérification, et Sites.Selected seule est un avertissement, car chaque site SharePoint exige une autorisation).

Pour Google, la vérification est credentials : Google a accepté le compte de service ou le jeton d’actualisation du compte qui a accordé l’accès, et la réponse nomme le compte auquel les calendriers doivent être visibles. Un refus est une vérification échouée et fait passer la connexion à error avec last_error ; un succès la ramène à ready.

Elle ne juge pas le partage d’un calendrier, une politique d’accès à une boîte aux lettres ni une autorisation de site, ce que prouve une source ou une synchronisation quand elle s’exécute. Au plus 30 par minute par organisation.

Crée un nouveau lien de consentement à usage unique (consent_url, valide jusqu’à consent_expires_at) pour une connexion en mode screenrig_app, à envoyer à la personne qui le complète : l’administrateur Microsoft 365 ou le titulaire du compte Google. Il remplace tout lien précédent.

Une connexion qui fonctionne reste telle quelle jusqu’à ce que le nouveau consentement soit terminé ; cela permet donc aussi de renouveler une connexion passée à error (consentement retiré, accès révoqué) ou de la déplacer vers un autre locataire ou compte. Le lien est un identifiant du consentement : ne l’envoyez qu’à cette personne.

Quand la personne a terminé, le navigateur revient à GET /oauth/connections/{provider}/callback et est redirigé vers la page de la connexion dans le tableau de bord, qui lit status et last_error. Une connexion en mode own_app n’a pas d’étape de consentement (409 resource_conflict) ; un serveur sans l’application de screenRIG pour le fournisseur répond 409 connection_app_not_configured.

L’adresse vers laquelle Microsoft renvoie le navigateur d’un administrateur Microsoft 365 après la page de consentement de l’administrateur (et de nouveau après l’étape d’ouverture de session qui la suit) pour une connexion en mode screenrig_app.

Elle ne porte aucun identifiant : le state signé de la requête est la seule autorité, il est vérifié avant que rien de ce qu’il nomme ne soit lu, et il n’est honoré que tant qu’il correspond au consentement en attente de la connexion.

Le premier retour nomme un locataire, qui n’est pas authentifié : la réponse est une redirection vers la page d’ouverture de session de ce locataire, dont le code est échangé avec le secret de l’application et un vérificateur PKCE que seul ce serveur peut dériver, et le locataire que porte le jeton d’ID est celui que la connexion enregistre une fois qu’un jeton d’identifiants client prouve que l’application y détient ses permissions.

Chaque résultat après un state vérifié redirige vers la page de la connexion dans le tableau de bord (/dashboard/connections/{id}?consent=connected ou ?consent=failed), qui lit status et last_error ; le texte d’erreur est construit à partir de phrases fixes et de la propre réponse d’erreur de Microsoft (son code AADSTS), jamais à partir de ce que la requête du callback portait.

Un state inconnu, expiré, utilisé, remplacé ou qui concerne une connexion supprimée affiche une page qui ne nomme rien. Ne répond que sur l’hôte d’API sous lequel les callbacks sont enregistrés.

L’adresse vers laquelle Google renvoie le navigateur du titulaire du compte après la page de consentement, pour une connexion en mode screenrig_app.

Elle ne porte aucun identifiant : le state signé de la requête est la seule autorité, il est vérifié avant que rien de ce qu’il nomme ne soit lu, et il n’est honoré que tant qu’il correspond au consentement en attente de la connexion. screenRIG échange le code avec le secret de l’application et un vérificateur PKCE que seul ce serveur peut dériver, exige que la portée calendrier ait été accordée (une personne peut la décocher sur la page de consentement) et un jeton d’actualisation, lit le compte qui a accordé l’accès dans le jeton d’ID que Google a renvoyé lors de cet appel, scelle le jeton d’actualisation et ajoute connection.connected.

Chaque résultat après un state vérifié redirige vers la page de la connexion dans le tableau de bord (/dashboard/connections/{id}?consent=connected ou ?consent=failed), qui lit status et last_error. Un state inconnu, expiré, utilisé, remplacé ou qui concerne une connexion supprimée affiche une page qui ne nomme rien.

Ne répond que sur l’hôte d’API sous lequel les callbacks sont enregistrés.