Skip to main content
This guide walks you through connecting your Google Workspace domain to an integration that uses a GCP service account with domain-wide delegation. This is a headless, server-to-server authentication method — there is no interactive login, and the integration accesses Gmail, Calendar, and Contacts data on behalf of users in your domain.

​
Before installing a Google (Workspace Delegation) integration

You will need:
  • Google Cloud Platform (GCP) access with permission to create service accounts (typically Owner or Editor on a GCP project).
  • Google Workspace super-admin access to your domain (required to authorize domain-wide delegation).

​
1. Enable the required APIs

  1. Go to the Google Cloud Console.
  2. Select (or create) a GCP project that will own the service account.
  3. Navigate to APIs & Services > Library.
  4. Enable the APIs your integration needs:
    • Gmail API for Gmail integrations.
    • Google Calendar API for Calendar integrations.
    • People API for Contacts integrations.

​
2. Create a service account

  1. In the Google Cloud Console, navigate to IAM & Admin > Service Accounts.
  2. Click Create Service Account.
  3. Enter a name and an optional description.
  4. Click Create and Continue, then Done. You do not need to grant any project-level IAM roles for domain-wide delegation as the authorization happens in the Workspace Admin console in step 4.

​
3. Create and download a key

  1. From the Service Accounts page, click on the service account you just created.
  2. Note the Unique ID (a numeric client ID, e.g. 123456789012345678901). You will need this in the next step.
  3. Go to the Keys tab.
  4. Click Add Key > Create new key.
  5. Select JSON as the key type and click Create.
  6. A JSON file will be downloaded. Store it securely — this file contains credentials that can impersonate any user in your Workspace domain once delegation is authorized.
You will need to base64-encode the contents of this file before providing it during installation. Use the command that matches your environment: macOS (Terminal) 
base64 -i service-account-key.json
Linux, Git Bash, or WSL 
base64 -w 0 service-account-key.json
Windows (PowerShell) 
[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path 'service-account-key.json')))
Copy the encoded string (a long single line). You will paste it when installing the integration.

​
4. Authorize domain-wide delegation

This step grants the service account permission to impersonate users in your Workspace domain. It must be performed by a super-admin of the Google Workspace domain.
  1. Go to the Google Admin console.
  2. Navigate to Security > Access and data control > API controls.
  3. Click Manage Domain Wide Delegation.
  4. Click Add new.
  5. In Client ID, paste the numeric Unique ID of the service account from step 3.
  6. In OAuth scopes, enter a comma-separated list of the scopes your integration needs. For example:
    • Gmail (read/write): https://mail.google.com/
    • Gmail (read-only): https://www.googleapis.com/auth/gmail.readonly
    • Calendar (read/write): https://www.googleapis.com/auth/calendar
    • Calendar (read-only): https://www.googleapis.com/auth/calendar.readonly
    • Contacts (read/write): https://www.googleapis.com/auth/contacts
    • Contacts (read-only): https://www.googleapis.com/auth/contacts.readonly
  7. Click Authorize.
Changes to domain-wide delegation can take up to 24 hours to propagate, though most take only a few minutes. If the integration returns unauthorized_client errors immediately after installation, wait and retry.

​
5. Gather your connection details

You will need to share the following information with the integration builder:
InputWhere to find it
Service Account KeyThe base64-encoded contents of the JSON key file from step 3.
User EmailsA full list of email addresses of all the users whose data the integration should access (e.g. user1@company.com, user2@company.com).
ScopesThe exact list of OAuth scopes you authorized in step 4 (or a subset).

​
Troubleshooting

​
unauthorized_client error

Sample error message: unauthorized_client: Client is unauthorized to retrieve access tokens using this method This means that either:
  • The service account’s numeric Client ID was not added to Manage Domain Wide Delegation in the Admin console (revisit step 4), or
  • One or more scopes provided to the integration were not a part of the scopes authorized in step 4.

​
invalid_grant error

Sample error message: invalid_grant: Invalid email or User ID This means that a user email you provided is not a valid active user in the Workspace domain. Workspace delegation does not work for suspended or deleted users. Confirm that the user’s address exists in Admin console > Directory > Users.