Connecting Google Workspace Integrations with a Service Account

Updated:


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:
IntegrationAPI to enable
Google DriveGoogle Drive API
GmailGmail API
Google CalendarGoogle Calendar API
Google SheetsGoogle Sheets API
Google DocsGoogle Docs API
Google SlidesGoogle Slides API
Google FormsGoogle Forms API
Google TasksGoogle Tasks API
Google ContactsPeople API
Google MeetGoogle Meet API + Google Calendar API
Workspace DirectoryAdmin 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):

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

IntegrationScope(s) to authorize
Google Drivehttps://www.googleapis.com/auth/drive
Gmailhttps://mail.google.com/
Google Calendarhttps://www.googleapis.com/auth/calendar
Google Sheetshttps://www.googleapis.com/auth/spreadsheets
Google Docshttps://www.googleapis.com/auth/documents
Google Slideshttps://www.googleapis.com/auth/presentations
Google Formshttps://www.googleapis.com/auth/forms.body, https://www.googleapis.com/auth/forms.responses.readonly
Google Taskshttps://www.googleapis.com/auth/tasks
Google Contactshttps://www.googleapis.com/auth/contacts
Google Meethttps://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/meetings.space.readonly
Workspace Directoryhttps://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:

FieldValue
Service Account EmailThe client_email from the JSON key file.
Service Account Private KeyThe 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

ErrorLikely cause
unauthorized_clientThe scope isn't authorized in domain-wide delegation, or the Client ID is wrong. Re-check Step 5A.
403 ... has not been used in projectThe API isn't enabled for the project (Step 2).
400 invalid_grant / Invalid JWT SignatureThe private key was pasted incorrectly (truncated, or newlines lost). Re-copy the full private_key value.
Empty results / 404 for a user's dataMissing 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).
Share
All guidesAccounting Account Type Hierarchy in UnifiedAdvertising Report Metrics by IntegrationAmazon S3: Required IAM PermissionsATS to Vector DB: How to Power Talent Intelligence with Real-Time DataBuilding AI applications with Unified and LangbaseConcur & Concur (Company) — Connection GuideConfigure Greenhouse Native Candidate WebhooksConfigure Salesforce Meetings and Notes for UnifiedConnect Amazon Seller Central to Unified.toConnecting BambooHR via OAuth 2Correct WelcomeKit Scopes for Jungle IntegrationCreating Ads using the Unified Ads APICreating Walmart Items via UnifiedEnd-Users, Integrations, and ConnectionsEnriching Unified Objects with Custom MetadataEnterprise-managed authorization (EMA) with a static keyEnterprise-managed authorization (EMA) with a workspace secretEnterprise-managed authorization (EMA) with Microsoft Entra IDExtended observability — pushing API logs to ClickHouseExtended observability — pushing API logs to Grafana / LokiExtended Observability - Pushing API Logs to your Datadog InstanceFacebook Messenger Webhook SetupFireflies Integration GuideGetting started with WorkableHandling Delegated vs. Application Scopes in Microsoft IntegrationsHiBob & Unified: connection and time off guideHow long are logs retainedHow to access employees and usersHow to add API support for the Create Activity in CrelateHow to Associate a Connection ID with Your End-UserHow to build a Candidate Assessment product withHow to build a candidate sourcing or job board app with Unified.toHow to build a Discord support bot with Unified.to and LangbaseHow to Build a Fintech Application with Unified's Payments APIHow to Build an E-Commerce Product Integration with UnifiedHow to build an invoicing system with Unified.toHow to build Enterprise Search using RAGHow to configure Bullhorn Redirect URI for creating a connectionHow to configure webhooks in HubSpotHow to configure webhooks in Thrive LearningHow to configure webhooks in Toast for UnifiedHow to Connect Anthropic to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Cohere to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Google Gemini to Real-Time SaaS Data with Unified.to MCP ServerHow to connect HiBob (Bob) to Unified with OAuth 2.0How to Connect LLMs to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect OpenAI to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Zoom and Zoom PhoneHow to create a Connection In Microsoft TeamsHow to create a token-based connection in HighlevelHow to Create a Unified.to Connection to HighLevelHow to Create a Xero Connection in Unified.toHow to create and configure webhooksHow to create Connection with HubspotHow to customize portal URLs for Stripe and GoCardlessHow to filter webhook eventsHow-to Get a Private Support Channel for Your Unified IntegrationHow to get help fromHow to get your 8x8 Connect API Key, Account ID and SMS Subaccount ID (optional): Step-by-step guideHow to get your ADP Workforce Now Oauth2 client ID, Oauth2 client secret, Oauth2 PEM certificate and Oauth2 private key: Step-by-step guideHow to get your Amazon S3 AWS Region, AWS S3 Key, AWS S3 Secret and AWS S3 Bucket(s) (optional, comma-separated): Step-by-step guideHow to get your Ashby API Key: Step-by-step guideHow to get your Brex API token: Step-by-step guideHow to get your Bullhorn OAuth2 Client ID, OAuth2 Client Secret, API Username and API Password: Step-by-step guideHow to get your Ceridian Dayforce Username, Password and Client Namespace: Step-by-step guideHow to get your Crelate API key: Step-by-step guideHow to get your Dashlane API Key: Step-by-step guideHow to get your Deel Access Token: Step-by-step guideHow to get your Dialpad API Key: Step-by-step guideHow to get your Discord OAuth 2 credentials and bot tokenHow to get your ELMO client ID and client secret: Step-by-step guideHow to get your Gainsight Client ID, Client Secret and Gainsight API Domain: Step-by-step guideHow to get your Greenhouse API Key and Job board token: Step-by-step guideHow to get your Helpscout API Key: Step-by-step guideHow to get your HiBob Service User ID and Service User Token: Step-by-step guideHow to get your HighLevel API Key and Location ID: Step-by-step guideHow to get your HubSpot developer key and OAuth 2 credentials (Legacy Apps)How to get your Humaans API Key: Step-by-step guideHow to get your iCIMS API Username, API Password and Customer ID: Step-by-step guideHow to get your JobDiva Client ID, Username/email and Password: Step-by-step guideHow to get your Jobvite API Key, API Key Secret and Email: Step-by-step guideHow to get your Lever API Key: Step-by-step guideHow to get your Loxo Agency slug, API Key and Agency ID: Step-by-step guideHow to get your Microsoft Active Directory / Entra ID Client ID, Client Secret and Tenant ID: Step-by-step guideHow to get your Microsoft Azure AD OAuth 2 credentialsHow to get your OAuth 2 credentials for GmailHow to get your OAuth 2 credentials for Microsoft Dynamics 365How to get your OAuth 2 credentials in PipeDriveHow to get your OpenAI API Key: Step-by-step guideHow to get your Paycom SID/Username and Token/Password: Step-by-step guideHow to get your PCRecruiter Username, Password, Database ID, App Key and App ID: Step-by-step guideHow to get your SAP SuccessFactors (OpenID Connect) Username, Password, Client ID, Client Secret, Dependency Name, IAS Host and API URL: Step-by-step guideHow to get your SAP SuccessFactors Username, Company ID, Password and API URL: Step-by-step guideHow to get your Shopify Admin API access token and Store ID: Step-by-step guideHow to get your Wayfair Client ID, Client Secret and Vendor Encrypted Key: Step-by-step guideHow to get your Workable API Token and Subdomain: Step-by-step guideHow to get your yotpo APP Key / Store ID and Secret Key: Step-by-step guideHow to Handle Attachments in Invoice, Bill and Credit MemoHow to Manage Google Ad Manager Orders, Line Items and Creatives with theHow to migrate or import your integrations into Unified.toHow to obtain your GitHub OAuth2 credentialsHow to Power Claude with Live Customer Data Using Unified MCPHow to receive assessment orders from an ATS with Unified.toHow to register a Google developer app and get OAuth 2 credentialsHow to Register a HiBob Developer App and Get OAUTH2 CredentialsHow to register a Salesforce developer app and get OAuth 2 credentialsHow to register a Slack developer account and get OAuth 2 credentialsHow to Register a Workday Developer App and Get OAUTH2 CredentialsHow to Register a Workday Developer App and Get OAUTH2/ SOAP CredentialsHow to Register a ZendeskSell Developer App and Get OAUTH2 CredentialsHow to Register a Zoho Developer App and Get OAUTH2 CredentialsHow to Register an ADP Developer App and Get OAUTH2 CredentialsHow to Register an Atlassian Developer App and Get OAUTH2 CredentialsHow to Register your Facebook OAuth2 ApplicationHow to Register your Google Ads OAuth2 ApplicationHow to Register your MetaAds OAuth2 applicationHow To Request & Write Raw Integration DataHow to Retrieve Microsoft Dynamics 365 Business Central CredentialsHow to set up a custom API URL with a CNAMEHow to Set Up a Google Meet Meeting Bot with UnifiedHow to set up a HiBob marketplace installHow to Set Up a Microsoft Teams Bot with UnifiedHow to Set Up a Microsoft Teams Meeting Bot with UnifiedHow to Set Up a Webex Meeting Bot with UnifiedHow to Set Up a Zoom Meeting Bot with UnifiedHow to set up and configure NotionHow to set up Google Business Profile API access and get OAuth 2 credentialsHow to Set Up LinkedIn Webhooks with UnifiedHow to set up native webhooks for QuickBooks Online with UnifiedHow to set up Slack webhooks using event subscriptionsHow to set up Telegram (bot) with Unified.toHow to set up your scopes in HubSpotHow to setup a Freshbooks developer appHow to setup a TikTok Shop applicationHow to Setup AWS Assume Role for AWS Secret ManagerHow to setup Oracle JD EdwardsHow to Setup Quickbooks DesktopHow to setup Sage 100 with Unified.toHow to test webhooks in the Synthetic Data (Sandbox) environmentHow to troubleshoot unhealthy connectionsHow to troubleshoot unhealthy webhooksHow to Use Decision Models with the Unified GenAI APIHow to use SCIM with the Unified APIHow to use the Passthrough APIHow to Use Unified.to's Generative AI API with OpenAI and ClaudeHow to use User Provisioning and Verification with UnifiedHow virtual webhook retry and recovery worksIntegration set-up guide for LeverManaging custom validation rules in SalesforceNetSuite Authentication Setup for UnifiedNotice of Deprecation of Fields and Objects (Nov 2025)Oracle HCM / Taleo OAuth Credentials GuideRetrieval-Augmented Generation (RAG)SalesForce (External Client Apps) on Multiple OrganizationsSAML Single-Sign-OnScaling MCP Tools with Anthropic's (& OpenAI's) Defer LoadingScaling MCP Tools with Anthropic's Programmatic Tool CallingSet Environments for your Unified.to WorkspaceSetting up a Slack Bot Connection with Unified.toSetting up OAuth 2 Credentials for Greenhouse's APIsTrello Connection Guide in UnifiedUnderstanding OAuth2 Authorization flowsUnderstanding Response Time Headers in the Unified APIUnified Assessment API: Embed Assessments Inside ATS PlatformsUnified's MCP ServerUnified MCP Server with LangChain and LangGraphUnlock real-time data with virtual webhooksUse Unified to sign in your users into your applicationVincere OAuth Setup Guide for UnifiedWhy you can't use Unified's OAuth2 credentials to authorize your end users on ProductionWorkable: Creating candidates and attaching them to jobsWorkday vs Workday Legacy — Why Unified.to Supports BothWorking with hierarchical tree data in Storage, Messaging, and KMS APIs
Are we missing anything? Let us know
Was this page helpful?