Table of Contents

Connected Accounts

Last updated:

Connected Accounts links your Oscova user to Google or Microsoft so approved tools can use those services with your permission.

Note

OAuth is the sign-in flow where an external provider, such as Google or Microsoft, asks whether Oscova may access selected services for your account.

Supported providers

The current page shows two providers:

  • Google for Gmail, Calendar, and YouTube tools.
  • Microsoft for Outlook, Microsoft To Do, and Microsoft Graph tools.

Each provider card can show Available, Unavailable, Connected as, or Not connected. Connect is disabled when the provider is unavailable.

Why a provider can be unavailable

Google and Microsoft require a shared OAuth app configuration before users can connect personal accounts. An administrator configures that app in the admin OAuth provider card by saving the provider client ID and client secret.

If the admin clears a provider client ID, that provider is disabled. Users cannot repair this from Connected Accounts. They need an administrator to configure the provider again.

On the admin side, the first save for a provider requires both a client ID and client secret. Later saves may leave the secret blank to keep the existing stored secret. Clearing the client ID removes that provider app configuration.

Connected Accounts stores user tokens, not general API keys. Each token belongs to the signed-in Oscova user, is encrypted in that user's credential store, and is hidden from the Credentials page as a managed entry. The shared OAuth client ID and secret belong to the administrator's system configuration.

User tokens are protected by that user's Vault Password key. Shared OAuth secrets are protected by the operator who saved them. After a Host restart, either kind remains unavailable until its protection owner signs in and unlocks. Another account cannot silently adopt an existing shared secret.

Connect an account

  1. Open Settings > Connections > Connected Accounts.
  2. Select Connect on an available provider.
  3. Complete the provider sign-in and consent flow.
  4. Return to Oscova and confirm the card shows the connected account.

Google requests offline access so Oscova can refresh the token without asking you to sign in for every tool call. Google scopes currently include OpenID profile/email, Gmail read/send, Calendar read-only, and YouTube read-only access.

Microsoft requests OpenID profile/email, offline_access, and Microsoft Graph scopes for mail read/send, Microsoft To Do read/write, and basic user profile lookup.

The callback must complete in the same signed-in Oscova session that started the flow. Oscova checks the one-time OAuth state value and verifies the initiating user before it exchanges the authorization code.

Oscova builds the callback from the address used to open the app. Use an app address that the same browser can return to after provider consent. A stale host name, reverse-proxy address, or inaccessible callback URL can prevent completion.

Connected-account tools call Google or Microsoft over the network. They are external egress and are blocked in an air-gapped run. Oscova refreshes expiring access tokens when a refresh token is available.

Disconnect an account

Select Disconnect to remove Oscova's saved token for that provider. The card shows a spinner while the request runs, then returns to Not connected.

Disconnecting in Oscova stops future tool calls from using the saved connection. It does not delete your external account. If you also want to revoke consent at the provider, use that provider's security or app-permissions dashboard.

Troubleshooting

  • Connect is disabled: ask an administrator to configure the provider's OAuth app.
  • The browser returns an error: retry from the same signed-in Oscova session that started the flow.
  • Provider not configured: ask an administrator to save the provider client ID and client secret.
  • Invalid state or missing code: start the connection again from the Connected Accounts card.
  • The connected email is missing: the provider did not return an email. The token can still be saved.
  • A tool still cannot access the service: confirm the active agent is allowed to use that tool and that the provider granted the required scopes.
  • A previously connected tool asks you to reconnect: the refresh token may be missing, expired, or rejected. Disconnect and complete the connection flow again.
  • The connection is unavailable after Oscova restarted: enter your Vault Password when prompted before reconnecting.
  • Disconnect fails: retry after refreshing the settings page. Unsupported provider names are rejected.
  • A different user needs access: that user must connect their own account. OAuth tokens are scoped to the signed-in Oscova user.