API Connessioni

Elenca le connessioni del progetto, le più recenti per prime, al massimo 200 per pagina; restituisci next_cursor come after per la successiva.

Una connessione è l’accesso riutilizzabile del progetto a Microsoft o a Google per le origini che funzionano senza supervisione: un’origine dati microsoft365 o google_calendar, una connessione Power BI e un account di sincronizzazione dei media SharePoint ne indicano una in config.connection_id invece di portare credenziali proprie (docs/connections.md).

Un segreto, una chiave o un token di aggiornamento non viene mai restituito: secret indica se ne è conservato uno e un indizio che non è segreto. Una lettura non porta mai un link di consenso.

Crea una connessione a Microsoft (provider microsoft) o a Google (provider google). La modalità own_app è l’app propria del cliente: per Microsoft, config.tenant_id (l’ID della directory o il dominio principale; common, organizations e consumers vengono rifiutati), config.client_id e secret (il valore di uno dei segreti client dell’app); per Google, secret è il file di chiave JSON dell’account di servizio.

Il segreto è sigillato e non viene mai restituito. La modalità screenrig_app usa l’app propria di screenRIG e non accetta né config né secret: la connessione viene creata pending_consent e la risposta porta consent_url, un link monouso (valido fino a consent_expires_at) per la persona che lo completa.

Per Microsoft è un amministratore Microsoft 365, che dà il consenso all’app di screenRIG per il tenant; il browser poi accede al tenant che Microsoft indica, così la connessione registra il tenant confermato, mai uno che un callback si limita a dichiarare.

Per Google è il titolare dell’account, che concede l’accesso in sola lettura ai calendari che l’account può vedere; screenRIG conserva sigillato il token di aggiornamento e l’indirizzo dell’account. Il link è una credenziale di un solo consenso: invialo solo a quella persona.

Un server senza l’app di screenRIG per il provider risponde 409 connection_app_not_configured, e le connessioni own_app continuano a funzionare. Un’organizzazione ha al massimo 50 connessioni in tutti i suoi progetti (connection_limit_reached). Aggiunge connection.created.

Un nuovo tentativo identico con la stessa Idempotency-Key restituisce la stessa connessione (un nuovo tentativo screenrig_app riceve un nuovo link di consenso, che sostituisce il primo).

Una connessione, con il suo stato, il suo ultimo errore e il suo ultimo test.

Modifica il nome di una connessione o, in modalità own_app, le sue credenziali: config.tenant_id e config.client_id (Microsoft) oppure secret (un segreto inviato sostituisce quello sigillato; uno omesso viene conservato). Una connessione in modalità screenrig_app può solo essere rinominata: collegala di nuovo (POST /api/connections/{id}/connect) per cambiare chi ha dato il consenso.

Una modifica delle credenziali riporta la connessione a ready, cancella last_error e last_test e ritira ogni token emesso per le vecchie credenziali. Aggiunge connection.updated. If-Match protegge la revisione.

Elimina una connessione da cui non legge nulla. Finché un’origine dati, una connessione Power BI o un account di sincronizzazione dei media la usa, la risposta è resource_conflict, che li indica (used_by elenca il loro tipo e ID).

L’eliminazione non pone fine al lato del fornitore: un tenant Microsoft 365 mantiene l’app di screenRIG finché il suo amministratore non la rimuove, e un account Google mantiene la sua concessione finché il titolare non la revoca. Aggiunge connection.deleted. If-Match protegge la revisione.

Accede con la connessione e memorizza la risposta come last_test.

Per Microsoft i controlli sono credentials (Microsoft ha emesso un token app per il tenant) e permissions (quali tra Calendars.Read, Sites.Selected, Files.Read.All, Sites.Read.All e Place.Read.All il token dell’app porta; un’app che non ne ha nessuna non supera il controllo, e Sites.Selected da sola è un avviso, perché ogni sito SharePoint richiede una concessione).

Per Google il controllo è credentials: Google ha accettato l’account di servizio o il token di aggiornamento dell’account che ha concesso l’accesso, e la risposta indica l’account a cui i calendari devono essere visibili. Un rifiuto è un controllo fallito e porta la connessione a error con last_error; un successo la riporta a ready.

Non giudica la condivisione di un calendario, una policy di accesso a una casella di posta né una concessione su un sito, cosa che un’origine o una sincronizzazione dimostra quando viene eseguita. Al massimo 30 al minuto per organizzazione.

Crea un nuovo link di consenso monouso (consent_url, valido fino a consent_expires_at) per una connessione in modalità screenrig_app, da inviare alla persona che lo completa: l’amministratore Microsoft 365 o il titolare dell’account Google. Sostituisce qualsiasi link precedente.

Una connessione funzionante resta com’è finché il nuovo consenso non è completato, quindi questo rinnova anche una passata a error (consenso rimosso, accesso revocato) o la sposta su un altro tenant o account. Il link è una credenziale del consenso: invialo solo a quella persona.

Quando la persona ha finito, il browser torna a GET /oauth/connections/{provider}/callback e viene inoltrato alla pagina della connessione nella dashboard, che legge status e last_error. Una connessione in modalità own_app non ha un passaggio di consenso (409 resource_conflict); un server senza l’app di screenRIG per il provider risponde 409 connection_app_not_configured.

Dove Microsoft invia il browser di un amministratore Microsoft 365 dopo la pagina di consenso dell’amministratore (e di nuovo dopo il passaggio di accesso che la segue) per una connessione in modalità screenrig_app.

Non porta alcuna credenziale: lo state firmato nella query è l’unica autorità, viene verificato prima di leggere qualsiasi cosa nomini, e viene rispettato solo finché è il consenso in sospeso della connessione.

Il primo ritorno indica un tenant, che non è autenticato: la risposta è un reindirizzamento all’accesso di quel tenant, il cui codice viene riscattato con il segreto dell’app e un verifier PKCE che solo questo server può derivare, e il tenant che porta il token ID è quello che la connessione registra dopo che un token di credenziali client dimostra che l’app vi detiene le sue autorizzazioni.

Ogni esito dopo uno state verificato reindirizza alla pagina della connessione nella dashboard (/dashboard/connections/{id}?consent=connected o ?consent=failed), che legge status e last_error; il testo dell’errore è costruito da frasi fisse e dalla risposta di errore di Microsoft (il suo codice AADSTS), mai da ciò che la query del callback portava.

Uno state sconosciuto, scaduto, usato, sostituito o di una connessione eliminata mostra una pagina che non indica nulla. Risponde solo sull’host dell’API sotto cui sono registrati i callback.

Dove Google invia il browser del titolare dell’account dopo la pagina di consenso per una connessione in modalità screenrig_app.

Non porta alcuna credenziale: lo state firmato nella query è l’unica autorità, viene verificato prima di leggere qualsiasi cosa nomini, e viene rispettato solo finché è il consenso in sospeso della connessione. screenRIG riscatta il codice con il segreto dell’app e un verifier PKCE che solo questo server può derivare, richiede che lo scope del calendario sia stato concesso (una persona può deselezionarlo nella pagina di consenso) e un token di aggiornamento, legge l’account che ha concesso l’accesso dal token ID restituito da Google in quella chiamata, sigilla il token di aggiornamento e aggiunge connection.connected.

Ogni esito dopo uno state verificato reindirizza alla pagina della connessione nella dashboard (/dashboard/connections/{id}?consent=connected o ?consent=failed), che legge status e last_error. Uno state sconosciuto, scaduto, usato, sostituito o di una connessione eliminata mostra una pagina che non indica nulla.

Risponde solo sull’host dell’API sotto cui sono registrati i callback.