API de Conexões

Lista as conexões do projeto, as mais recentes primeiro, no máximo 200 por página; devolva next_cursor como after para a próxima.

Uma conexão é o acesso reutilizável do projeto à Microsoft ou ao Google para fontes que rodam sem supervisão: uma fonte de dados microsoft365 ou google_calendar, uma conexão do Power BI e uma conta de sincronização de mídia do SharePoint nomeiam uma em config.connection_id em vez de levar credenciais próprias (docs/connections.md).

Um segredo, uma chave ou um token de atualização nunca é devolvido: secret mostra se há um guardado e uma dica que não é secreta. Uma leitura nunca traz um link de consentimento.

Cria uma conexão com a Microsoft (provider microsoft) ou o Google (provider google). O modo own_app é o aplicativo próprio do cliente: para a Microsoft, config.tenant_id (o ID do diretório ou o domínio primário; common, organizations e consumers são recusados), config.client_id e secret (o valor de um dos segredos de cliente do aplicativo); para o Google, secret é o arquivo de chave JSON da conta de serviço.

O segredo é selado e nunca devolvido. O modo screenrig_app usa o aplicativo próprio do screenRIG e não aceita config nem secret: a conexão é criada como pending_consent e a resposta traz consent_url, um link de uso único (válido até consent_expires_at) para a pessoa que o conclui.

Para a Microsoft, é um administrador do Microsoft 365, que dá consentimento ao aplicativo do screenRIG para o tenant; o navegador então faz login no tenant que a Microsoft nomeia, de modo que a conexão registra o tenant confirmado, nunca um que um callback apenas afirme.

Para o Google, é o titular da conta, que concede acesso somente leitura às agendas que a conta pode ver; o screenRIG guarda o token de atualização selado e o endereço da conta. O link é uma credencial de um único consentimento: envie-o somente a essa pessoa.

Um servidor sem o aplicativo do screenRIG para o provedor responde 409 connection_app_not_configured, e as conexões own_app continuam funcionando. Uma organização tem no máximo 50 conexões em todos os seus projetos (connection_limit_reached). Adiciona connection.created.

Uma nova tentativa exata com a mesma Idempotency-Key devolve a mesma conexão (uma nova tentativa de screenrig_app recebe um novo link de consentimento, que substitui o primeiro).

Uma conexão, com seu status, seu último erro e seu último teste.

Altera o nome de uma conexão ou, no modo own_app, as credenciais dela: config.tenant_id e config.client_id (Microsoft) ou secret (um segredo enviado substitui o selado; um omitido é mantido). Uma conexão no modo screenrig_app só pode ser renomeada: conecte-a de novo (POST /api/connections/{id}/connect) para mudar quem deu o consentimento.

Uma mudança nas credenciais devolve a conexão a ready, limpa last_error e last_test e aposenta todos os tokens emitidos para as credenciais antigas. Adiciona connection.updated. If-Match protege a revisão.

Exclui uma conexão pela qual nada lê. Enquanto uma fonte de dados, uma conexão do Power BI ou uma conta de sincronização de mídia a usa, a resposta é resource_conflict, nomeando-as (used_by lista o tipo e o ID delas).

Excluir não encerra o lado do fornecedor: um tenant do Microsoft 365 mantém o aplicativo do screenRIG até que o administrador o remova, e uma conta do Google mantém a concessão até que o titular a revogue. Adiciona connection.deleted. If-Match protege a revisão.

Faz login com a conexão e guarda a resposta como last_test.

Para a Microsoft, as verificações são credentials (a Microsoft emitiu um token de aplicativo para o tenant) e permissions (quais entre Calendars.Read, Sites.Selected, Files.Read.All, Sites.Read.All e Place.Read.All o token do aplicativo traz; um aplicativo sem nenhuma delas não passa na verificação, e Sites.Selected sozinha é um aviso, porque cada site do SharePoint precisa de uma concessão).

Para o Google, a verificação é credentials: o Google aceitou a conta de serviço ou o token de atualização da conta que concedeu o acesso, e a resposta nomeia a conta para a qual as agendas devem estar visíveis. Uma recusa é uma verificação que falhou e move a conexão para error com last_error; um sucesso a devolve a ready.

Ela não julga o compartilhamento de uma agenda, uma política de acesso a caixa de correio nem uma concessão de site, o que uma fonte ou sincronização prova quando roda. No máximo 30 por minuto por organização.

Gera um novo link de consentimento de uso único (consent_url, válido até consent_expires_at) para uma conexão no modo screenrig_app, para enviar à pessoa que o conclui: o administrador do Microsoft 365 ou o titular da conta do Google. Ele substitui qualquer link anterior.

Uma conexão que funciona fica como está até o novo consentimento ser concluído, então isso também renova uma que passou a error (consentimento removido, acesso revogado) ou a move para outro tenant ou conta. O link é uma credencial do consentimento: envie-o somente a essa pessoa.

Quando a pessoa termina, o navegador volta a GET /oauth/connections/{provider}/callback e é encaminhado à página da conexão no dashboard, que lê status e last_error. Uma conexão no modo own_app não tem etapa de consentimento (409 resource_conflict); um servidor sem o aplicativo do screenRIG para o provedor responde 409 connection_app_not_configured.

Para onde a Microsoft envia o navegador de um administrador do Microsoft 365 depois da página de consentimento do administrador (e de novo depois da etapa de login que vem em seguida) para uma conexão no modo screenrig_app.

Ela não leva nenhuma credencial: o state assinado na consulta é a única autoridade, é verificado antes de ler qualquer coisa que ele nomeie e só é aceito enquanto for o consentimento pendente da conexão.

O primeiro retorno nomeia um tenant, que não é autenticado: a resposta é um redirecionamento para o login desse tenant, cujo código é resgatado com o segredo do aplicativo e um verificador PKCE que só este servidor consegue derivar, e o tenant que o token de ID traz é o que a conexão registra depois que um token de credenciais de cliente prova que o aplicativo tem lá as suas permissões.

Todo resultado após um state verificado redireciona para a página da conexão no dashboard (/dashboard/connections/{id}?consent=connected ou ?consent=failed), que lê status e last_error; o texto do erro é montado a partir de frases fixas e da própria resposta de erro da Microsoft (o código AADSTS dela), nunca do que a consulta do callback trazia.

Um state desconhecido, expirado, usado, substituído ou de uma conexão excluída mostra uma página que não nomeia nada. Responde apenas no host da API sob o qual os callbacks estão registrados.

Para onde o Google envia o navegador do titular da conta depois da página de consentimento para uma conexão no modo screenrig_app.

Ela não leva nenhuma credencial: o state assinado na consulta é a única autoridade, é verificado antes de ler qualquer coisa que ele nomeie e só é aceito enquanto for o consentimento pendente da conexão. O screenRIG resgata o código com o segredo do aplicativo e um verificador PKCE que só este servidor consegue derivar, exige que o escopo de agenda tenha sido concedido (a pessoa pode desmarcá-lo na página de consentimento) e um token de atualização, lê a conta que concedeu o acesso no token de ID que o Google devolveu nessa chamada, sela o token de atualização e adiciona connection.connected.

Todo resultado após um state verificado redireciona para a página da conexão no dashboard (/dashboard/connections/{id}?consent=connected ou ?consent=failed), que lê status e last_error. Um state desconhecido, expirado, usado, substituído ou de uma conexão excluída mostra uma página que não nomeia nada.

Responde apenas no host da API sob o qual os callbacks estão registrados.