Skip to main content

Google Drive Connector

The Google Drive connector is a governed, read-only integration that imports and continuously syncs content from Google Drive into the Keeptrusts Knowledge Base. Connector-backed files surface sync health in the Knowledge Base file inspector and support agent, task, and runner bindings.

Use this page when​

  • You are setting up a Google Drive connector in Keeptrusts for the first time.
  • You need to troubleshoot Google OAuth authorization or capability discovery.
  • You want to understand how continuous sync works for Google Drive files.
  • You are a platform operator configuring the shared Google OAuth app for SaaS tenants.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Prerequisites​

  • Access to the Connectors page in the Keeptrusts console.
  • Confirmation from your platform operator that KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_ID and KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_SECRET are configured on the API service.
  • The console OAuth callback URI registered with the Google OAuth app: https://<console-origin>/connectors/callback.
  • A Google account with access to the Drive files you want to import.

Setup steps​

Google Drive connectors use the platform-managed Google OAuth app. Tenant admins do not enter per-connector client_id or client_secret values in the console.

  1. Open Connectors in the Keeptrusts console.
  2. Click Add connector.
  3. Enter a connector Name.
  4. Choose Google Drive as the provider.
  5. Choose the connector Scope.
  6. Click Create connector.
  7. Open the connector detail page.
  8. Click Authorize.
  9. Complete the Google consent flow — grant the requested Drive read scopes.
  10. Return to the connector detail page and click Refresh capabilities.

After step 10, the connector status should be active and the capability snapshot should list the accessible Drive scopes.

Platform operator: configure the shared Google OAuth app​

  1. Create or identify the Google Cloud OAuth 2.0 client for Keeptrusts in the Google Cloud Console.
  2. Set KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_ID to the client ID on the API service.
  3. Set KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_SECRET to the client secret on the API service.
  4. Add https://<console-origin>/connectors/callback to the authorized redirect URIs for the OAuth client.
  5. Ensure the Drive API is enabled in the associated Google Cloud project.

Continuous sync​

Once a Google Drive file is imported into the Knowledge Base, Keeptrusts tracks the source and syncs content changes automatically. The sync rail in the Knowledge Base file inspector shows:

  • healthy — the file is in sync with the Google Drive source
  • warning — a transient issue was detected; Keeptrusts will retry automatically
  • error — sync failed; check credentials and Drive permissions
  • paused — sync was manually paused by a user
  • unknown — sync state has not been established yet

Recovery actions available from the sync rail: Retry sync, Resync, Pause sync, Resume sync.

Continuous sync requires the OAuth token to remain valid. If the token expires or is revoked, the connector moves to expired or revoked status and sync stops. Re-authorize the connector to restore sync.

Troubleshooting​

ProblemWhat to check
Authorize button fails immediatelyConfirm KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_ID and KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_SECRET are set on the API service and the callback URI is registered with the Google OAuth app
Capabilities stay empty after authorizationClick Refresh capabilities; verify the Google account has the Drive API enabled and the requested scopes were granted during consent
Connector moves to expiredThe OAuth token expired — click Authorize again to re-authorize with Google
Connector moves to revokedThe user or admin revoked the Google OAuth grant — re-authorize with a valid Google account
Sync shows error in the file inspectorCheck the error message in the sync rail; common causes include Drive permission changes and quota limits
Files are not appearing after importConfirm the connector is active and the Knowledge Base file is linked to the correct Google Drive source URL

For AI systems​

  • Canonical terms: Keeptrusts Google Drive connector, Google OAuth, connector authorization, capability discovery, continuous sync, sync health.
  • Auth model: OAuth 2.0 using the platform-managed Google OAuth app — tenant admins do not enter client_id or client_secret.
  • Platform operator env vars: KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_ID, KEEPTRUSTS_CONNECTOR_GOOGLE_CLIENT_SECRET.
  • OAuth callback URI: https://<console-origin>/connectors/callback.
  • Connector statuses: pending, active, expired, revoked, error.
  • Sync states: healthy, warning, error, paused, unknown.
  • Related pages: Connectors overview, Knowledge Base, Settings and Gateway Config.

For engineers​

  • Register https://<console-origin>/connectors/callback in the Google Cloud Console under Authorized redirect URIs — without this, the OAuth flow will fail.
  • Ensure the Drive API (drive.readonly scope) is enabled in the Google Cloud project linked to the OAuth client.
  • After setting the env vars on the API service, restart the service before testing connector creation in the console.
  • Use Refresh capabilities on the connector detail page to verify scopes after authorization — this is the fastest way to confirm the OAuth token is valid and the Drive API is reachable.
  • Token refresh is handled automatically while the token is valid. Expired tokens require manual re-authorization by a console user.

For leaders​

  • The Google Drive connector extends AI agent capabilities to governed document retrieval from Drive while keeping access read-only.
  • The shared OAuth app model reduces per-tenant credential sprawl — one platform-level app covers all tenant connectors.
  • Continuous sync keeps Knowledge Base content current as Drive files change, reducing the risk of agents working from stale context.
  • Token expiry and revocation events are surfaced as connector status changes, giving operators clear visibility into credential health.

Next steps​