---
title: "Connecting Google Workspace Integrations with a Service Account"
img: https://unified.to/images/logo.svg
date: 2026-05-21T16:13:00.000Z
tag: Guides
description: "Unified API supports two ways to authenticate Google integrations, the standard interactive OAuth2 flow (a user clicks \"Allow\"), or a service account for..."
url: "https://docs.unified.to/guides/connecting_google_workspace_integrations_with_a_service_account"
---

# Connecting Google Workspace Integrations with a Service Account
------
_May 21, 2026_

Unified API supports two ways to authenticate Google integrations: the standard interactive **OAuth2** flow (a user clicks "Allow"), or a **service account** for server-to-server access with no human in the loop. This guide covers the service account path: how to create one, how to grant it access to your data, and what to enter in Unified API.


## **When to use a service account**


Use a service account when you want a backend system to access Google data without a user logging in each time — for example, syncing every mailbox in your company, reading a shared Drive, or managing your Workspace directory. For most Workspace data (Gmail, Calendar, Drive files owned by users, etc.) the service account must **impersonate** a user via **domain-wide delegation (DWD)**. For a few APIs (Analytics, Merchant Center, Campaign Manager) you instead just **share** the resource with the service account's email — no delegation needed.


---


## **Step 1 — Create a Google Cloud project**

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project (or select an existing one) using the project picker at the top.
3. Note the **Project ID** — you'll see it referenced in the key file later.

## **Step 2 — Enable the APIs you need**

1. Navigate to **APIs & Services → Library**.
2. Search for and **Enable** the API for each integration you'll use:

| **Integration**     | **API to enable**                     |
| ------------------- | ------------------------------------- |
| Google Drive        | Google Drive API                      |
| Gmail               | Gmail API                             |
| Google Calendar     | Google Calendar API                   |
| Google Sheets       | Google Sheets API                     |
| Google Docs         | Google Docs API                       |
| Google Slides       | Google Slides API                     |
| Google Forms        | Google Forms API                      |
| Google Tasks        | Google Tasks API                      |
| Google Contacts     | People API                            |
| Google Meet         | Google Meet API + Google Calendar API |
| Workspace Directory | Admin SDK API                         |
If an API isn't enabled, calls will fail with a `403 ... API has not been used in project` error.


## **Step 3 — Create the service account**

1. Go to **APIs & Services → Credentials → Create credentials → Service account**.
2. Give it a name (e.g. `unified-api-sync`) and click **Create and continue**.
3. You can skip the optional "grant access" steps for now. Click **Done**.
4. You'll land on the service account list. Note its **email** — it looks like:`unified-api-sync@your-project-id.iam.gserviceaccount.com`

## **Step 4 — Generate a key**

1. Click the service account, then open the **Keys** tab.
2. **Add key → Create new key → JSON → Create.**
3. A `.json` file downloads. **Store it securely** — Google does not let you re-download it.

The file looks like this (the two fields you need are highlighted):


```json
{  
	"type": "service_account",  
	"project_id": "your-project-id",  
	"private_key_id": "abc123...",  
	"private_key": "-----BEGIN PRIVATE KEY-----\nMIIEv...\n-----END PRIVATE KEY-----\n",   ← Service Account Private Key  
	"client_email": "unified-api-sync@your-project-id.iam.gserviceaccount.com",            ← Service Account Email  
	"client_id": "11223344...",  
	"token_uri": "https://oauth2.googleapis.com/token",  
	...
}
```


---


## **Step 5 — Grant the service account access to your data**


This is the step that differs by API. Pick the path that matches your integration.


### **Path A — Domain-wide delegation (Workspace user data)**


Required for **Gmail, Calendar, Drive (user files), Sheets, Docs, Slides, Forms, Tasks, Contacts, Meet, and Directory**. This lets the service account act _as_ a specific user in your Workspace.

1. On the service account's detail page, note its **Client ID** (the numeric `client_id` from the JSON, also called "Unique ID").
2. As a Workspace **super admin**, go to the [Admin Console → Security → Access and data control → API controls → Domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation).
3. Click **Add new** and enter:
    - **Client ID**: the service account's numeric Client ID.
    - **OAuth scopes**: a comma-separated list of the scopes for the APIs you'll use (see the scope table below).
4. **Authorize.** Changes can take a few minutes to propagate.
> Only the scopes you authorize here will work. If you add the Drive integration later, you must come back and add the Drive scope.

### **Path B — Resource sharing (no delegation)**


For APIs where data is owned by an account/property rather than a user, you skip DWD and just grant the service account's **email** access inside the product:

- **Google Analytics** — add the service account email as a user on the GA4 property.
- **Merchant Center** — add it as a user in Merchant Center settings.
- **Campaign Manager / Display & Video 360** — add it as a user in the platform.

(These integrations aren't part of the Workspace set covered here but follow the same key-creation steps.)


---


## **Step 6 — Scopes per integration**


When configuring domain-wide delegation (Path A), authorize the matching scope(s). These are exactly the scopes Unified API requests when minting tokens:


| **Integration**     | **Scope(s) to authorize**                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Google Drive        | `https://www.googleapis.com/auth/drive`                                                                                                                                         |
| Gmail               | `https://mail.google.com/`                                                                                                                                                      |
| Google Calendar     | `https://www.googleapis.com/auth/calendar`                                                                                                                                      |
| Google Sheets       | `https://www.googleapis.com/auth/spreadsheets`                                                                                                                                  |
| Google Docs         | `https://www.googleapis.com/auth/documents`                                                                                                                                     |
| Google Slides       | `https://www.googleapis.com/auth/presentations`                                                                                                                                 |
| Google Forms        | `https://www.googleapis.com/auth/forms.body`, `https://www.googleapis.com/auth/forms.responses.readonly`                                                                        |
| Google Tasks        | `https://www.googleapis.com/auth/tasks`                                                                                                                                         |
| Google Contacts     | `https://www.googleapis.com/auth/contacts`                                                                                                                                      |
| Google Meet         | `https://www.googleapis.com/auth/calendar`, `https://www.googleapis.com/auth/meetings.space.readonly`                                                                           |
| Workspace Directory | `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` |
---


## **Step 7 — Configure the connection in Unified API**


When creating the connection, choose the **Service Account** authentication option and fill in three fields:


| **Field**                       | **Value**                                                                                                                                                                                                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Service Account Email**       | The `client_email` from the JSON key file.                                                                                                                                                                                                                                 |
| **Service Account Private Key** | The `private_key` from the JSON key file — paste it whole, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines.                                                                                                                              |
| **Subject**                     | _(Optional)_ The email of the Workspace user to impersonate via domain-wide delegation. **Required for most Workspace data** (e.g. Gmail needs a mailbox owner). Leave blank only if the service account itself owns the data or you've shared resources directly with it. |
That's it. Unified API signs a short-lived JWT with your private key, exchanges it with Google for an access token (caching it until it expires), and uses it for all API calls — no further interaction needed.


---


## **Troubleshooting**


| **Error**                                                | **Likely cause**                                                                                                |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `unauthorized_client`                                    | The scope isn't authorized in domain-wide delegation, or the Client ID is wrong. Re-check Step 5A.              |
| `403 ... has not been used in project`                   | The API isn't enabled for the project (Step 2).                                                                 |
| `400 invalid_grant` / `Invalid JWT Signature`            | The private key was pasted incorrectly (truncated, or newlines lost). Re-copy the full `private_key` value.     |
| Empty results / `404` for a user's data                  | Missing or wrong **Subject** — you're querying as the service account itself instead of impersonating the user. |
| `403 Not Authorized to access this resource` (Directory) | The impersonated **Subject** must be a Workspace **admin** with rights to the directory data.                   |
### **Security notes**

- The private key grants standing access to your data — store it in a secret manager, never in source control.
- Authorize only the scopes you actually use; broad scopes increase blast radius if the key leaks.
- Rotate keys periodically (create a new key, update the connection, delete the old key).