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
- Go to the Google Cloud Console.
- Select (or create) a GCP project that will own the service account.
- Navigate to APIs & Services > Library.
- 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
- In the Google Cloud Console, navigate to IAM & Admin > Service Accounts.
- Click Create Service Account.
- Enter a name and an optional description.
- 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
- From the Service Accounts page, click on the service account you just created.
- Note the Unique ID (a numeric client ID, e.g.
123456789012345678901). You will need this in the next step. - Go to the Keys tab.
- Click Add Key > Create new key.
- Select JSON as the key type and click Create.
- 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.
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.- Go to the Google Admin console.
- Navigate to Security > Access and data control > API controls.
- Click Manage Domain Wide Delegation.
- Click Add new.
- In Client ID, paste the numeric Unique ID of the service account from step 3.
- 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
- Gmail (read/write):
- 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.
