Skip to main content

​
About Google Workspace

Google Workspace (formerly G Suite) provides email, calendar, drive and directory services for organisations. Connecting Google Workspace to Serval lets you automate common admin tasks, enforce security policies and modify user data directly inside Serval workflows.

​
What the Google Workspace integration enables

CapabilityConnection MethodDescription
Access ManagementOAuth or Service AccountCreate, update, and manage users and their permissions
Automation workflowsOAuth or Service AccountManage groups, and organizational data. Create aliases, manage settings, and more
Knowledge Base SyncService Account onlyAutomatically sync and index Google Drive content (Docs, Sheets, Slides) for semantic search
Gmail DelegationService Account onlyManage email delegation settings

​
Choose your connection method

We offer two different configuration mechanisms for Google Workspace:
  • Standard OAuth integration:
    • Simple integration process
    • Suitable for basic user and group management
    • No domain-wide delegation required
  • Service Account integration:
    • More manual configuration required
    • Full control over scopes and permissions
    • Required for advanced APIs (e.g., Gmail delegation APIs)
    • Enables domain-wide delegation
To get started, navigate to the “Apps” page and click “Connect to Google Workspace”: Image(10) Pn Select “Authorize with Google” for standard OAuth or “Use Service Account” for service account integration.

​
Service Account Integration Setup

​
Step 1: Create Google Cloud Project and Service Account

  1. Navigate to console.cloud.google.com and login
  2. Create a new project:
    • Click “Select Project” → “New Project”
    • Choose any name for your project
Image(12) Pn Image(13) Pn
  1. Create a service account:
    • Navigate to “Credentials” → “Create Credentials” → “Service Account”
    • Name your service account and create it (other fields optional)
Image(16) Pn

​
Step 2: Enable Required APIs

Critical: Enable the required APIs in your Google Cloud project:
  1. Navigate to “APIs & Services” → “Library”
  2. Search for and enable the following APIs:
    • Admin SDK API (required for user and group management)
    • Gmail API (required for Gmail operations)
    • Google Drive API (required for Drive file operations)
    • Google Sheets API (required for Sheets operations)
  3. Click “Enable” for each API
Note: API enablement takes 5-10 minutes to propagate. If you encounter 403 errors initially, wait and try again.

​
Step 3: Configure Service Account Permissions

Grant Serval permission to impersonate your service account:
  1. Go to your service account → “Permissions” tab → “Grant Access”
  2. Add principal: [email protected]
  3. Assign role: “Service Account Token Creator”
Image(17) Pn Image(18) Pn Note: If you encounter domain restriction errors, complete Step 5: Organization Policies first.

​
Step 4: Configure Domain-Wide Delegation

  1. Get your service account’s Client ID:
    • Go to your service account → “Details” page
    • Copy the “Client ID” (long numeric string, e.g., 116634191637610572786)
  2. Configure in Google Workspace Admin Console:
    • Navigate to admin.google.com → “Security” → “Access and data control” → “API controls” → “Manage Domain Wide Delegation”
    • Click “Add New”
    • Enter your service account’s Client ID
    • Add the required scopes based on your needs:
https://www.googleapis.com/auth/admin.directory.user
https://www.googleapis.com/auth/admin.directory.group
https://www.googleapis.com/auth/admin.directory.group.member
https://www.googleapis.com/auth/apps.groups.settings
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.metadata
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/spreadsheets.readonly
https://www.googleapis.com/auth/cloud-platform
All scopes (comma-separated for easy copy/paste): 
https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.group.member,https://www.googleapis.com/auth/apps.groups.settings,https://www.googleapis.com/auth/gmail.settings.basic,https://www.googleapis.com/auth/gmail.settings.sharing,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/drive.metadata,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/cloud-platform
  • Click “Authorize”
Image(20) Pn Image(21) Pn Important: The https://www.googleapis.com/auth/cloud-platform scope is required for impersonation.
Scope capabilities:Admin Directory:Gmail:Calendar:Drive & Knowledge Base:
  • https://www.googleapis.com/auth/drive - 🔑 Required for Knowledge Base sync - Full access to Google Drive files
  • https://www.googleapis.com/auth/drive.metadata - 🔑 Required for incremental sync - Access to file metadata for change detection
Sheets:

​
Step 5: Organization Policies (Optional)

Only complete this step if you received domain restriction errors in Step 3.
  1. Navigate to Google Cloud Console → Organization Policies
  2. Search for iam.allowedPolicyMemberDomains
  3. Select “Domain Restricted Sharing” → “Manage Policy”
  4. Select “Override Parent’s Policy” and “Merge with Parent”
  5. Click “Add a rule” → “Custom” → “Allow”
  6. Enter C04gvbkuc as the custom value
  7. Save the policy
Image(23) Pn Image(24) Pn Image(25) Pn If you don’t have Organization Policy access:
  • Request access from your Organization Administrator
  • Contact your Google Cloud Administrator
  • Use a different Google Cloud project where you have admin rights

​
Complete Integration Setup

After completing the service account setup:
  1. Return to Serval → “Apps” → “Available” → “Google Workspace” → “Connect”
  2. Enter the required information:
    • Google Workspace domain: Your organization’s domain (e.g., company.com)
    • Service Account email: Your service account’s email address
    • Default subject: An admin user in your domain (e.g., [email protected])
    • Scopes: The comma-separated list from Step 4
  3. Click “Save”
Your integration is now ready to use!

​
Knowledge Base Sync

Once your Google Workspace integration is configured with the Drive API scopes, you can enable knowledge base synchronization to make your Google Drive content searchable within Serval.

​
What Gets Synced

Serval automatically syncs and indexes the following Google Drive content types:
  • Google Docs - Full text content converted to markdown
  • Google Sheets - Exported as CSV and converted to markdown tables
  • Google Slides - Slide text content as markdown
  • Folders - Folder hierarchy for organization (no content to index)
Not supported yet: - Files from other formats (PDF, Word, etc.) are not currently synced - Comments and suggestions within documents - Revision history

​
How Sync Works

Initial Sync:
  1. Serval discovers all accessible Google Drive files and folders
  2. Downloads and converts supported file types to searchable markdown
  3. Creates embeddings for semantic search
  4. Maintains folder hierarchy for organization
Incremental Updates:
  • Serval automatically detects changes to synced files using the Drive Changes API
  • Only modified files are re-downloaded and re-indexed
  • The drive.metadata scope enables efficient change detection
Folder Selection Required: You must explicitly select which folders to sync from your Google Drive. For security and privacy, Serval will not sync any files until you configure folder selection.Navigate to your Google Workspace integration settings → Knowledge Source tab to select folders. Only files within the selected folders (and their subfolders) will be synced and indexed for search.

​
Required Scopes for Knowledge Base Sync

At minimum, you need these scopes for knowledge base functionality: 
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive.metadata.readonly
For full functionality including Sheets export: 
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.metadata
https://www.googleapis.com/auth/spreadsheets.readonly
The drive.metadata scope is critical for incremental sync. Without it, Serval must perform full re-syncs which are much slower and more resource-intensive.

​
Managing Your Knowledge Base

After enabling sync:
  1. Navigate to your Google Workspace app in Serval
  2. Go to the “Knowledge Source” tab
  3. Click “Sync” to start an initial sync
  4. Monitor sync progress and view synced items
  5. Toggle individual items’ visibility to control what’s searchable
Sync frequency: Incremental syncs run automatically every few hours to detect changes. You can manually trigger a sync at any time.

​
Troubleshooting Knowledge Base Sync

“Failed to list Drive files” error:
  • Verify the drive and drive.metadata scopes are configured in domain-wide delegation
  • Check that the Drive API is enabled in your Google Cloud project
  • Ensure your default subject user has access to the files you’re trying to sync
“No files synced” but files exist:
  • Check folder permissions - Serval can only sync files accessible to the default subject user
  • Verify files are of supported types (Docs, Sheets, Slides)
  • Check that files aren’t in the Trash
Slow initial sync:
  • Initial syncs can take time for large Drive accounts (hundreds of files)
  • Consider implementing folder filtering to limit scope
  • Incremental syncs after the initial sync are much faster

​
Troubleshooting

​
Common Setup Issues

If you encounter errors during setup, verify these configurations:
ComponentVerification
APIs EnabledGoogle Cloud Console → APIs & Services → Enabled APIs
Service Account PermissionsService Account → Permissions → Verify [email protected] has “Token Creator” role
Domain-Wide DelegationGoogle Workspace Admin Console → Security → API Controls → Verify Client ID is listed

​
Error Messages and Solutions

​
”impersonate: status code 401: unauthorized_client”

Missing: Service account permissions
Fix: Complete Step 3: Configure Service Account Permissions

​
”Admin SDK API has not been used in project [PROJECT_ID] before or it is disabled”

Missing: API enablement
Fix: Complete Step 2: Enable Required APIs

​
”Client is unauthorized to retrieve access tokens using this method”

Missing: Domain-wide delegation
Fix: Complete Step 4: Configure Domain-Wide Delegation

​
”Domain restricted sharing policy”

Missing: Organization policy configuration
Fix: Complete Step 5: Organization Policies

​
Getting Help

If you continue to experience issues:
  1. Verify all steps in the setup process are complete
  2. Wait 10-15 minutes for Google services to propagate changes
  3. Check that your default subject user has admin privileges in Google Workspace