> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google (workspace delegation)

This guide walks you through connecting your Google Workspace domain to an integration that uses a GCP service account with [domain-wide delegation](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority). 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](https://console.cloud.google.com/).
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)**

```bash theme={null}
base64 -i service-account-key.json
```

**Linux, Git Bash, or WSL**

```bash theme={null}
base64 -w 0 service-account-key.json
```

**Windows (PowerShell)**

```powershell theme={null}
[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](https://admin.google.com/).
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**.

<Note>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.</Note>

### 5. Gather your connection details

You will need to share the following information with the integration builder:

| Input                   | Where to find it                                                                                                                        |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Service Account Key** | The base64-encoded contents of the JSON key file from step 3.                                                                           |
| **User Emails**         | A full list of email addresses of all the users whose data the integration should access (e.g. `user1@company.com, user2@company.com`). |
| **Scopes**              | The 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**.