Google Workspace - Serval Documentation

About Google Workspace

Google Workspace (formerly G Suite) connects Serval to your organization’s Google tenant so you can automate day-to-day IT and admin tasks - managing users, groups, aliases, calendar resources, and more - directly from Serval workflows. It also lets Serval index your Google Drive content so it can be searched as a knowledge source. You can connect using one of two methods, and which one you choose determines what Serval can do. Standard OAuth (“Sign in with Google”) is enough for basic user and group management. A Service Account with domain-wide delegation unlocks Knowledge Base (Drive) sync and Gmail delegation in addition to everything OAuth supports. Authentication: OAuth 2.0 (Sign in with Google) for basic user/group management, or a Service Account with domain-wide delegation for full capabilities including Drive knowledge sync and Gmail delegation. Data sync: Background sync of users, groups, and group members on a recurring schedule; Drive content is indexed continuously (service account only). Automation and provisioning workflows run on demand.

What the Google Workspace integration enables

Capability	Description
User sync	Syncs your Google Workspace users into Serval on a recurring schedule, so they’re available for assignments, lookups, and workflows.
Group sync	Syncs Google Groups and their members. Each group carries a single “member” entitlement (Member access to that group). A full sync runs every 16 hours, with an incremental sync every 4 hours.
Group access provisioning	Adds and removes users to and from Google Groups, so access changes can be automated through Serval workflows.
Knowledge Base sync	Service account only. Indexes your Google Drive content so it can be searched as a knowledge source. Knowledge sync uses direct service account impersonation rather than the standard OAuth path.
Admin and automation workflows	Manages users, groups, aliases, group settings, calendar resources, mobile devices, contact delegation, and more, depending on the scopes you grant.
Gmail delegation	Service account only. Manages Gmail delegation and settings. Requires domain-wide delegation.

Anything available in the Google Workspace API can be accessed through Serval, as long as the matching scopes are granted.

Get your credentials

How you set up credentials depends on the connection method you choose.

Service Account (full capabilities)
OAuth (basic user/group management)

Use the Service Account method for Knowledge Base (Drive) sync and Gmail delegation. First, create a Google Cloud project and service account. Then authorize domain-wide delegation and choose one credential path:

Let Serval impersonate the service account without a key. This is the default for Serval Cloud.
Create a JSON key. Self-hosted deployments require this path, and Serval Cloud also supports it.

Before you start

Service account setup uses two separate admin systems:

A Google Workspace super admin must authorize domain-wide delegation.
A Google Cloud project administrator must create and configure the service account.
A Google Cloud Organization Policy Administrator (roles/orgpolicy.policyAdmin) is required only when Domain Restricted Sharing blocks Serval’s external principal. The JSON key path avoids this policy change.

Create a Google Cloud project and service account

Open the Google Cloud Console and select or create the project that will own the integration.Go to IAM & Admin → Service Accounts, then create a service account. You don’t need to grant project-level roles during creation.

Enable the required APIs

In the same project, go to APIs & Services → Library.Enable the APIs required for the features you plan to use:

Admin SDK API for user and group management
Google Drive API for Drive and Knowledge sync
Google Sheets API for Sheets export
Gmail API for Gmail delegation
IAM Service Account Credentials API for both Serval-managed impersonation and the JSON key path

New API settings can take 5-10 minutes to propagate. If a newly enabled API still reports an error, wait a few minutes and retry.

Serval Cloud without a key - allow Serval's principal in Domain Restricted Sharing

Serval’s regional service account is an external principal. Domain Restricted Sharing (iam.allowedPolicyMemberDomains) blocks external principals from IAM grants, so we need to add Serval’s customer ID to the policy before we can grant access. This requires the Google Cloud Organization Policy Administrator role (roles/orgpolicy.policyAdmin) on the project, or help from someone who has it.

Open Google Cloud Organization Policies.
Select the project that owns the service account in the resource picker.
Open Domain Restricted Sharing (iam.allowedPolicyMemberDomains), then click Manage policy.
Select Override parent’s policy, then click Add a rule.
Under Policy values, select Custom. Under Policy type, select Allow.
Keep every existing allowed value, including your own Google Workspace customer ID, and add:
is:C04gvbkuc
Save the policy and wait several minutes for it to propagate.

Don’t replace your existing allowed values. A project-level override replaces the inherited list, so omitting your own customer ID can block principals from your organization.

Adding Serval’s customer ID only makes Serval principals eligible for IAM grants in this project. It doesn’t grant access by itself.Without this exception, Google rejects the grant in the next step with:

IAM policy update failed
One or more users named in the policy do not belong to a permitted customer.

If you can’t change the organization policy, skip the next step and use the JSON key path.

Alternative path: use the Google Cloud CLI

Install and initialize the gcloud CLI using Google’s installation instructions:

gcloud init

Inspect the effective policy for the project:

gcloud org-policies describe iam.allowedPolicyMemberDomains \
  --project=PROJECT_ID \
  --effective \
  --format=yaml

Create domain-restricted-sharing.yaml. Copy every existing allowedValues entry from the effective policy, then add Serval’s customer ID:

domain-restricted-sharing.yaml

name: projects/PROJECT_ID/policies/iam.allowedPolicyMemberDomains
spec:
  rules:
    - values:
        allowedValues:
          - EXISTING_ALLOWED_VALUE
          - is:C04gvbkuc

Repeat the EXISTING_ALLOWED_VALUE line for every value in the effective policy. Replace PROJECT_ID with the project that owns the service account.Apply the project-level override:

gcloud org-policies set-policy domain-restricted-sharing.yaml

Run the describe command again without changing its arguments. Confirm that the effective policy contains every original value and is:C04gvbkuc.

The CLI path requires the same Organization Policy Administrator role as the console path. Applying an incomplete allowedValues list can block principals from your organization.

Serval Cloud only - grant Serval permission to impersonate your service account

Go to IAM & Admin → Service Accounts, select your service account, then open Permissions → Grant access.Under New principals, add Serval’s service account email for your region. Assign the Service Account Token Creator role.US region (app.serval.com) - copy and paste exactly:

serval@serval-424322.iam.gserviceaccount.com

EU region (app.eu1.serval.com) - copy and paste exactly:

serval-eu1@serval-424322.iam.gserviceaccount.com

Don’t grant the US principal to an EU-hosted organization or the EU principal to a US-hosted organization. Each region signs with its own identity, so a cross-region grant can’t mint tokens. Check your Serval address if you aren’t sure which region you use.

Don’t enter your own service account’s email here. The principal must be Serval’s service account for your region.

Create a JSON key (self-hosted, or as a Serval Cloud alternative)

Self-hosted deployments use the JSON key path. On Serval Cloud, this path is an alternative when Domain Restricted Sharing blocks Serval’s principal.Go to IAM & Admin → Service Accounts, select your service account, then open Keys → Add key → Create new key → JSON. Download the key. You’ll upload it in the Serval connect form.Next, open Permissions → Grant access on the same service account. Enter the service account’s own email under New principals, then assign Service Account Token Creator.You can also create the self-grant with gcloud:

gcloud iam service-accounts add-iam-policy-binding YOUR_SA_EMAIL \
  --member="serviceAccount:YOUR_SA_EMAIL" \
  --role="roles/iam.serviceAccountTokenCreator"

Once a key is on file, Serval calls Google as your service account. The self-grant authorizes token minting, and a Token Creator grant to Serval’s principal has no effect on this path.The IAM Service Account Credentials API must remain enabled. Both the domain-wide delegation entry and the Serval Scopes field must contain https://www.googleapis.com/auth/cloud-platform.

If Create new key is unavailable, an organization policy prevents service account key creation. A Google Cloud administrator must permit key creation or configure Serval-managed impersonation.

Copy the numeric Client ID

Open IAM & Admin → Service Accounts, select your service account, then open Details.Copy the numeric Unique ID / Client ID, a long number such as 116634191637610572786. You’ll use it in Google Admin.

Authorize domain-wide delegation in the Admin console

Open the Google Workspace Admin Console.Go to Security → Access and data control → API controls → Manage Domain Wide Delegation, then click Add new.Enter the numeric Client ID from the previous step.Select scopes to authorize. Use All Scopes for the full range of Serval capabilities (user and group sync, Drive Knowledge sync, Gmail delegation, calendar, and Sheets). Use Minimal Directory-Only Scopes if you only need basic user and group management (no Drive Knowledge sync or Gmail delegation).

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

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/cloud-platform

Comma-separated (copy/paste into Google Admin and the Serval Scopes field):

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

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/cloud-platform

Paste the comma-separated scopes into the OAuth scopes field, then click Authorize. Use the exact same comma-separated string in the Serval connect form (see Connect in Serval).

Enter the numeric Client ID, not the service account’s email address. Using the email is the single most common setup mistake. Use one delegation entry per Client ID.

https://www.googleapis.com/auth/cloud-platform is required in every scope set. Serval relies on it to mint tokens, and Google rejects token creation if it’s missing from the Admin delegation grant.

For background, see Google’s guides on controlling API access with domain-wide delegation, creating and managing service account keys, and service account impersonation. The delegation screen Serval links to on validation errors is Manage Domain-Wide Delegation.

Connect in Serval

The connect form differs depending on the method you chose.

Service Account
OAuth

Google Workspace domain

Required. Your Workspace domain. If left empty, Serval rejects the form with the error workspaceDomain is required.

Service Account email

Required. The target service account that Serval impersonates. This is your service account’s email - not the client_email from the JSON key. If left empty, Serval rejects the form with serviceAccountEmail is required. This value is shown again when you edit the connection so it round-trips into the form.

Default subject

Required. An admin user in your domain (for example, admin@company.com) that Serval impersonates. If left empty, Serval rejects the form with defaultSubject is required.

Scopes

Required. Paste the same comma-separated scope list you authorized in Google Admin domain-wide delegation. If left empty, Serval rejects the form with scopes are required.All Scopes (recommended) - 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/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

Minimal Directory-Only (user/group sync only, no Drive Knowledge or Gmail delegation):

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/cloud-platform

Serval automatically appends https://www.googleapis.com/auth/cloud-platform when it requests tokens, but Google’s delegation layer still rejects token creation unless that scope is also explicitly present in your Google Admin delegation grant.

Service Account Key (JSON)

Optional on Serval Cloud, US and EU regions (leave it empty for keyless impersonation, or upload your own key - see the JSON key step under Get your credentials). Effectively required on self-hosted (unless your operator pre-loaded the key). Paste or upload the JSON key file for your service account. Serval validates it and will reject:

An empty value: serviceAccountJson is required
Invalid JSON: serviceAccountJson is not valid JSON
The wrong type: serviceAccountJson must have type="service_account"
A missing client email: serviceAccountJson is missing client_email
A missing or malformed private key: serviceAccountJson is missing or malformed private_key

The serviceAccountJson is required error fires only when no key resolves from any source - the key you submit, then (when editing) the key already on file, then your deployment’s platform-level key - so on Serval Cloud, where the platform-level key is configured in both regions, leaving this field empty does not trigger it.If you do upload a key, make sure it is the service account’s key file - it starts with {"type": "service_account", ...} - not the OAuth client JSON.

On edit, the stored key is never shown back - you’ll see an empty field with a “key on file” indicator. Leaving it empty keeps the existing key. To rotate the key, paste or upload a new one.

Uploading a key on Serval Cloud switches Serval to calling Google as your own service account - make sure the service account holds Service Account Token Creator on itself, or token minting fails with an impersonation 403.

When you connect or update, Serval validates the impersonation chain end-to-end against Google before saving and surfaces Google’s real error verbatim (plus a link to the delegation screen). Trust this connect-time error text - background knowledge sync does not surface configuration errors and can appear as a silent, stalled spinner.

You can have Catalyst walk this setup with you. Paste this into a Catalyst session:

I am connecting Google Workspace to Serval with a service account, using the
JSON key path. Walk me through verifying each step: the Admin SDK and IAM
Service Account Credentials APIs are enabled, the service account has
roles/iam.serviceAccountTokenCreator granted on itself, the domain-wide
delegation entry uses the numeric client ID and includes
https://www.googleapis.com/auth/cloud-platform, and the Serval connect form
has the Workspace domain, service account email, a Default subject that is a
real admin user, the same comma-separated scope list, and the uploaded JSON
key. Then help me run the connection health checks and interpret any error
verbatim. Never ask me to paste the contents of the key file or any other
secret.

Google Workspace domain

Required. Your Workspace domain. If left empty, Serval rejects the form with workspaceDomain is required.

Authorize Serval through Google’s sign-in flow. After sign-in, Serval determines your Workspace ID automatically and verifies it against the domain you entered.

Verifying the connection

Before connecting in Serval, confirm these setup steps are complete:

Component	Verification
APIs enabled	Google Cloud Console → APIs & Services → Enabled APIs (Admin SDK, Drive, Sheets, Gmail, IAM Service Account Credentials)
Serval Cloud Token Creator	Your service account → Permissions → your region’s Serval principal (US: `serval@serval-424322.iam.gserviceaccount.com`; EU: `serval-eu1@serval-424322.iam.gserviceaccount.com`) has Service Account Token Creator. If you uploaded a JSON key instead, verify the service account has Service Account Token Creator on itself
Domain-wide delegation	Google Admin → Security → API controls → your service account’s numeric Client ID is listed with the matching scope set

After connecting, run the health checks - especially the first one - to confirm everything is working.

Test Google Workspace Connection verifies Serval can authenticate with Google. On success: Successfully authenticated with Google Workspace Admin API. On failure: Unable to connect to Google Workspace. Please verify your OAuth token or service account credentials are valid and have the necessary Admin SDK API access.
List Google Workspace Users lists a small sample of users. On success: Successfully listed users from Google Workspace (sample size: N). On failure: Unable to list users from Google Workspace. Please verify your credentials have the 'admin.directory.user' or 'admin.directory.user.readonly' scope.
List Google Workspace Groups lists a small sample of groups. On success: Successfully listed groups from Google Workspace (sample size: N). On failure: Unable to list groups from Google Workspace. Please verify your credentials have the 'admin.directory.group' or 'admin.directory.group.readonly' scope.
Test Google Drive API Access checks Drive access used for Knowledge Base sync. On success: Successfully accessed Google Drive API (sample files found: N). On failure it begins with Unable to access Google Drive API. followed by a branch-specific explanation.
List Google Shared Drives checks access to Shared Drives (Team Drives). On success: Successfully listed Shared Drives from Google Workspace (found: N). On failure it begins with Unable to list Shared Drives. followed by a branch-specific explanation.

If user sync works but the Drive health checks fail, this is usually expected for Service Account connections - and not a real problem. The two Drive health checks run through Serval’s OAuth proxy infrastructure, which doesn’t carry the service account impersonation context that the actual Knowledge sync uses. As a result, a Drive health check can fail even when Knowledge sync is working perfectly. The failure messages themselves tell you to ignore the result if Knowledge sync is working.

Scope reference

Use this table to customize your scope set. All scopes are prefixed with https://www.googleapis.com/auth/.

Admin Directory

Scope	Description
`admin.directory.user`	Manage users in your domain
`admin.directory.group`	Manage groups in your domain
`admin.directory.group.member`	Manage group memberships
`admin.directory.domain.readonly`	Read domain information
`apps.groups.settings`	Manage group settings

Gmail

Scope	Description
`gmail.settings.basic`	Manage basic Gmail settings
`gmail.settings.sharing`	Manage Gmail delegation settings

Calendar

Scope	Description
`calendar`	Full access to Google Calendar

Drive and Knowledge Base

Scope	Description
`drive`	Full access to Google Drive files. Required for Knowledge Base sync.
`drive.metadata`	Access to file metadata for change detection. Required for incremental Knowledge sync.

Sheets

Scope	Description
`spreadsheets`	Full access to Google Sheets
`spreadsheets.readonly`	Read-only access to Google Sheets

Platform

Scope	Description
`cloud-platform`	Required. Enables Serval to impersonate your service account.

Optional add-on scopes

Add these to the All Scopes list (in both Google Admin and Serval) only if you use the corresponding installable workflows:

Scope	Needed for
`admin.directory.user.alias`	Create, delete, or list user aliases
`admin.directory.device.mobile` and `admin.directory.device.mobile.action`	Approve pending mobile devices
`admin.directory.resource.calendar`	Manage calendar resources (rooms/equipment)
`admin.contact.delegation`	Contact delegation admin
`admin.directory.rolemanagement`	Read and manage admin roles and role assignments

Gotchas and troubleshooting

The scopes must be granted in BOTH places, including cloud-platform

Your scope list must be granted in two independent places that mirror each other: the Google Admin domain-wide-delegation entry and the Scopes field in Serval. Both must include https://www.googleapis.com/auth/cloud-platform. Serval auto-appends this scope when minting tokens, but Google’s delegation layer still rejects the request unless it’s explicitly present in the Admin grant. Minimal scope sets that omit cloud-platform will fail.

Authorize delegation by the numeric Client ID, not the service account email

In Google Admin → Manage Domain Wide Delegation, the Client ID field must contain the service account’s numeric Unique ID / Client ID (for example, 116634191637610572786), not its email address. Using the email is the single most common setup mistake. Use one delegation entry per Client ID.

'unauthorized_client' or 'not authorized for any of the scopes requested'

Errors like unauthorized_client, not authorized for any of the scopes requested, or Client is unauthorized to retrieve access tokens using this method mean the delegation scopes don’t match. Fix it by granting the full scope set (including cloud-platform) in the Google Admin domain-wide-delegation entry against the numeric Client ID. Serval surfaces this error from the token-minting step along with a link to the delegation screen.

'impersonate: status code 403' or 'failed to generate credentials for Google impersonated service account'

Both messages come from the same token-impersonation step. Workflow and API requests surface Google’s verbatim error (for example impersonate: status code 403: ... referencing the IAM Service Account Credentials API); some Serval logs and status surfaces still show the generic failed to generate credentials for Google impersonated service account wording. Either way, this points to one of: a missing cloud-platform scope, a missing “Service Account Token Creator” role on the target service account, or the IAM Service Account Credentials API not being enabled. Confirm cloud-platform is in your scope list, the required API is enabled in your Google Cloud project, and the correct principal has Service Account Token Creator on your service account. On Serval Cloud keyless setups, that principal is Serval’s service account for your region (US: serval@serval-424322.iam.gserviceaccount.com; EU: serval-eu1@serval-424322.iam.gserviceaccount.com). If you uploaded a JSON key, it’s your service account itself (the self-grant) - once a key is on file, grants to Serval’s principal no longer apply.

'Admin SDK API has not been used in project ... or it is disabled'

Enable the Admin SDK API in your Google Cloud project (APIs & Services → Library). Note that newly enabled APIs can take a few minutes to propagate.

User sync works but Drive doesn't (the silent-spinner symptom)

Directory calls (users and groups) and Drive/Knowledge calls authenticate through different paths. The Drive health checks also route through Serval’s OAuth proxy, which lacks the service account impersonation context the real Knowledge sync uses - so those checks can fail (with messages mentioning SERVICE_DISABLED, a 403/Forbidden, or a 401/unauthorized) even though Knowledge sync works. The failure messages tell Service Account users to ignore the result if Knowledge sync is working. If a Drive message references the OAuth proxy project, that’s a Serval-platform concern and not something you can fix in your own Google Cloud project.

Validate at connect time - background sync won't show the error

When you connect or update, Serval runs full impersonation validation against Google before saving and shows Google’s real error verbatim plus a link to the delegation screen. Background knowledge sync does not surface these errors - a misconfiguration there shows only as a stalled spinner. Always run the health checks (especially Test Google Workspace Connection) right after connecting, and trust the connect-time validation text over a stuck sync.

Connect-time validation only probes the directory when a directory scope is present

Serval always mints an impersonated token during validation (which catches delegation scope problems, target service account existence, the Token Creator role, and IAM API enablement). It additionally probes the directory for your default subject only when a directory scope (preferring admin.directory.user.readonly, otherwise admin.directory.user) is in your submitted list. Drive-, Gmail-, or Calendar-only connections are not forced to add a directory scope just to pass validation. The group readonly scope does not satisfy this probe.

Serval Cloud works keyless or with an uploaded key; self-hosted needs the JSON key

On Serval Cloud, the Service Account Key (JSON) field is optional - by default Serval signs with its own regional deployment service account and impersonates your target service account via the Token Creator role. Uploading your own JSON key is also supported on Serval Cloud: Serval then calls Google as your service account, which must hold Service Account Token Creator on itself (grants to Serval’s principal stop applying once a key is on file). The key path is useful when the Domain Restricted Sharing policy blocks adding external principals. On self-hosted, the JSON key is effectively required unless your operator pre-loaded the cluster secret for it.

The stored JSON key is never shown back; empty on edit means keep it

When editing a connection, Serval never echoes the stored JSON key - you’ll see an empty field with a “key on file” indicator. Leaving it empty keeps the existing key; paste or upload a new key to rotate. The JSON’s client email (your source service account) is never used to overwrite the Service Account email field (your target service account).

Resetting an OAuth connection to a completely clean state

If you connected with Sign in with Google and want to restart the authorization from scratch, delete the connection on both sides. In Serval: open Integrations, select your Google Workspace connection, and delete it (other data is retained if you reconnect later). On the Google side: sign in to the Google account that authorized the connection, open Manage your Google Account, go to Security, then Connections to third-party apps and services, select Serval, and delete all connections. Reconnecting afterwards walks through the full authorization flow as if connecting for the first time.

Need help? Contact support@serval.com for assistance with your Google Workspace integration.

​About Google Workspace

​What the Google Workspace integration enables

​Get your credentials

​Before you start

​Connect in Serval

​Verifying the connection

​Scope reference

​Admin Directory

​Gmail

​Calendar

​Drive and Knowledge Base

​Sheets

​Platform

​Optional add-on scopes

​Gotchas and troubleshooting

About Google Workspace

What the Google Workspace integration enables

Get your credentials

Before you start

Connect in Serval

Verifying the connection

Scope reference

Admin Directory

Gmail

Calendar

Drive and Knowledge Base

Sheets

Platform

Optional add-on scopes

Gotchas and troubleshooting