Skip to main content

​
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

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.
The Service Account method is required for Knowledge Base (Drive) sync and Gmail delegation. You’ll set up a Google Cloud project and service account, grant it domain-wide delegation in the Google Workspace Admin console, and - depending on your deployment - either grant Serval permission to impersonate it (Serval Cloud) or download a JSON key for it (self-hosted).
1

Create a Google Cloud project and service account

In the Google Cloud Console, create a project, then create a service account under IAM & Admin → Service Accounts.
2

Enable the required APIs

In APIs & Services → Library, enable the APIs you need: Admin SDK API (user and group management), Google Drive API (Drive and Knowledge sync), Google Sheets API (Sheets export), Gmail API (Gmail delegation), and IAM Service Account Credentials API (required for Serval Cloud impersonation).
API enablement can take 5-10 minutes to propagate. If a freshly enabled API still reports as disabled, wait a few minutes and retry.
3

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

On your service account, go to Permissions → Grant Access. In New principals, add Serval’s service account email (copy and paste exactly):
Assign the Service Account Token Creator role. This lets Serval impersonate your service account without a key. Serval’s service account email is not shown in the Serval connect form.
Do not enter your own service account’s email here. The principal must be Serval’s service account (serval@serval-424322.iam.gserviceaccount.com).
4

Self-hosted only - create a JSON key

Create a JSON key for your service account (Keys → Add Key → Create new key → JSON) and download it. You’ll paste or upload this in the Serval connect form.
5

Copy the numeric Client ID

Open your service account’s Details page and copy its numeric Unique ID / Client ID (a long numeric string such as 116634191637610572786). You’ll need this for the next step.
6

Authorize domain-wide delegation in the Admin console

In the Google Workspace Admin Console, go to Security → Access and data control → API controls → Manage Domain Wide Delegation → 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).
Comma-separated (copy/paste into Google Admin and the Serval Scopes field):
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 is missing from the Admin delegation grant.
7

If you hit a domain-restriction error

If granting the Token Creator role is blocked by a domain-restriction error, update the Domain Restricted Sharing organization policy (iam.allowedPolicyMemberDomains) in Google Cloud Console → Organization Policies so it also allows Serval’s organization customer ID: C04gvbkuc. Then retry the Token Creator 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.
1

Google Workspace domain

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

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.
3

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.
4

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:
Minimal Directory-Only (user/group sync only, no Drive Knowledge or Gmail delegation):
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.
5

Service Account Key (JSON)

Optional on Serval Cloud, 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, leaving this field empty does not trigger it.
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.
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.

​
Verifying the connection

Before connecting in Serval, confirm these setup steps are complete: 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

​
Gmail

​
Calendar

​
Drive and Knowledge Base

​
Sheets

​
Platform

​
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:

​
Gotchas and troubleshooting

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.
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.
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.
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 (Serval Cloud) serval@serval-424322.iam.gserviceaccount.com has Service Account Token Creator on your service account.
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.
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.
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.
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.
On Serval Cloud, the Service Account Key (JSON) field is optional - Serval signs with its own deployment service account and impersonates your target service account via the Token Creator role. On self-hosted, the JSON key is effectively required unless your operator pre-loaded the cluster secret for 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).
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 Applications, 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.