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

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

{  
    "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.
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:

Step 7 — Configure the connection in Unified API

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

Troubleshooting

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