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 “Applications” page in your team, select “Connect new” and click on “Google Workspace”:
Google Workspace connection option in Serval Apps page
Select “Sign in with Google” for standard OAuth or “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 a Project” → “New Project”
    • Choose any name for your project
Google Cloud Console Select Project menu
Google Cloud Console New Project creation dialog
  1. Create a service account:
    • Search for “Service account” by selecting the search bar at the top of the page, or by typing ”/” to activate search.
    • Select “Create service account”
    • Provide a Service account name and account ID.
    • All other fields are optional and you can select “Done” to complete Service account creation.
Google Cloud service account creation dialog

​
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 select enable for 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. Note: API selection is customizable to your use case.
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. Navigate to “IAM & Admin” → “Service Accounts” in your Google Cloud project
  2. Click on the service account you created in Step 1
  3. Go to the “Permissions” tab and click “Grant Access”
  4. Add the principal: serval@serval-424322.iam.gserviceaccount.com
  5. Assign the role: “Service Account Token Creator”
Google Cloud IAM Grant Access dialog
Google Cloud Service Account Token Creator role selection
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 Unique ID / Client ID:
    • Go to your service account → “Details” page
    • Copy the “Unique ID” / “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 Unique ID / Client ID in the “Client ID” field
Google Workspace Admin Add a new client ID dialog
  1. Select and authorize scopes:
    • We recommend using All Scopes for the full range of Serval capabilities. Use Minimal Scopes if you only need basic user and group management.
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/admin.directory.domain.readonly
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
Comma-separated (copy/paste into Google Admin Console): 
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/admin.directory.domain.readonly,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
The cloud-platform scope is required in both scope sets. It enables Serval to impersonate your service account. Removing it will cause authentication to fail.
For details on what each scope enables, see Scope Reference below. If you plan to use Knowledge Base Sync, make sure the Drive and Sheets scopes are included.
Having trouble with scopes or permissions? See Troubleshooting for common error messages and solutions.
  • Paste the comma-separated scopes into the “OAuth scopes” field
  • Click “Authorize”
Google Workspace Admin domain-wide delegation interface

​
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
Google Cloud organization policies list
Google Cloud Domain Restricted Sharing policy configuration
Google Cloud organization policy custom rule configuration
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

​
Step 6: Complete Connection

Return to Serval to complete the integration:
  1. Navigate to “Applications” → “Google Workspace” → “Connect” → “Service Account”
  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., admin@company.com)
    • Scopes: The comma-separated list from Step 4
  3. Click “Submit”
Your Google Workspace 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

​
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 serval@serval-424322.iam.gserviceaccount.com 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

​
Knowledge Base Sync Issues

​
”Failed to list Drive files”

  • 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 using folder selection to limit scope
  • Incremental syncs after the initial sync are much faster

​
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

​
Scope Reference

Below is a breakdown of what each Google API scope enables. Use this to decide which scopes are appropriate for your organization.

​
Admin Directory

ScopeDescription
admin.directory.userManage users in your domain
admin.directory.groupManage groups in your domain
admin.directory.group.memberManage group memberships
admin.directory.domain.readonlyRead domain information
apps.groups.settingsManage group settings

​
Gmail

ScopeDescription
gmail.settings.basicManage basic Gmail settings
gmail.settings.sharingManage Gmail delegation settings

​
Calendar

ScopeDescription
calendarFull access to Google Calendar

​
Drive and Knowledge Base

ScopeDescription
driveFull access to Google Drive files. Required for Knowledge Base sync.
drive.metadataAccess to file metadata for change detection. Required for incremental sync.

​
Sheets

ScopeDescription
spreadsheetsFull access to Google Sheets
spreadsheets.readonlyRead-only access to Google Sheets

​
Platform

ScopeDescription
cloud-platformRequired. Enables Serval to impersonate your service account.
All scopes are prefixed with https://www.googleapis.com/auth/. For example, admin.directory.user refers to https://www.googleapis.com/auth/admin.directory.user.