Skip to main content

Google Service Account Setup

Configuring a Google service account with domain-wide delegation for use with Caddi

A Google service account lets Caddi act across your Workspace domain without any individual signing in — useful for scheduled loops and shared-mailbox workflows. It is also the highest-privilege grant in Google Workspace, so it's worth reading the security notes before you set it up.

Domain-wide delegation applies to every user in your domain. There is no per-OU or per-group scoping in the delegation interface. A grant of full Gmail access means the key can read and delete any mailbox in the organization, and the resulting activity is attributed to the impersonated users rather than to the integration — which makes it hard to spot.

Grant the narrowest scopes that work, and treat the JSON key file as you would a domain administrator password.

No Google verification is needed on this path, regardless of scope. The super admin's delegation grant is the authorization and no consent screen is ever shown — which is the decisive practical advantage over an OAuth client when you need restricted scopes like full Gmail or Drive access.

Before you start

You'll need:

  • A Google Cloud project, with Service Account Admin and Service Account Key Admin on it

  • A Google Workspace Super Administrator — domain-wide delegation cannot be configured by anyone else

  • Owner or Admin access to your Caddi organization

Check for a blocking org policy first. Any Google Cloud organization created on or after 3 May 2024 has iam.disableServiceAccountKeyCreation enforced by default, which will stop you at the key-creation step. If it applies, an Org Policy Administrator has to set an exception before you begin.

Step 1: Enable the APIs

  1. In Google Cloud Console, go to APIs & Services → Library and filter to Google Workspace.

  2. Enable the APIs your loops need: Gmail, Google Drive, Google Calendar, Google Docs, Google Sheets, and Admin SDK if you need domain user or group lookups.

Step 2: Create the service account and its key

  1. Go to IAM & Admin → Service Accounts and click Create service account.

  2. Enter a display name such as caddi-integration. The email address is generated for you and cannot be changed later.

  3. Skip the "Grant this service account access to project" step. Cloud IAM roles grant no Google Workspace data access at all — a common and time-consuming misconception. Click Done.

  4. Open the service account and note two values: the email (ending @PROJECT_ID.iam.gserviceaccount.com) and the Unique ID — a roughly 21-digit number, also shown as Client ID under Advanced settings. You need the numeric ID for the next step.

  5. Go to the Keys tab and click Add key → Create new key → JSON → Create.

  6. The JSON file downloads immediately. This is the only copy — Google cannot reissue it.

If key creation fails with a policy error, the org policy noted above is blocking it. An Org Policy Administrator needs to grant an exception for this project.

Step 3: Authorize domain-wide delegation

This step happens in the Google Workspace Admin Console, not Cloud Console, and requires a Super Administrator.

The Client ID field wants the service account's numeric ID, not its email address, and not an apps.googleusercontent.com client ID. Pasting the service account email here is the most common failure — delegation then silently fails with unauthorized_client at token time, with nothing obviously wrong in the interface.

  1. Sign in to the Admin Console as a Super Administrator.

  2. Go to Security → Access and data control → API controls, then click Manage Domain Wide Delegation in the Domain wide delegation pane. The direct link is admin.google.com/ac/owl/domainwidedelegation.

  3. Click Add new.

  4. Client ID — paste the service account's numeric Unique ID from Step 2.

  5. OAuth scopes — enter the scope URLs as a comma-separated list.

  6. Click Authorize.

Changes can take up to 24 hours to propagate, though minutes is typical. If it isn't working immediately, wait before recreating anything. Your organization may also require a second super admin to approve the grant.

Step 4: Choose scopes

Every scope Caddi uses at runtime has to appear in the delegation grant, or the token request fails. Add them all here.

  1. https://www.googleapis.com/auth/gmail.modify — read, compose, and send mail

  2. https://www.googleapis.com/auth/drive — full Drive access

  3. https://www.googleapis.com/auth/calendar.events — read and write events

  4. https://www.googleapis.com/auth/documents — read and write Docs

  5. https://www.googleapis.com/auth/spreadsheets — read and write Sheets

Google's own guidance is to review these periodically and remove what isn't needed. Because the grant is domain-wide, every scope here is a scope across every mailbox and drive in your organization.

Step 5: Configure Google Service Account in Caddi

This step must be completed by a Caddi organization owner or admin.

  1. In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.

  2. Find Google - Custom Service Account in the list and click Configure.

Enter the following values:

  • Service Account Email — the client_email value from the JSON file

  • Private Key (PEM Format) — the private_key value from the JSON file. See the note below on pasting this correctly.

  • Private Key ID — the private_key_id value (40 hex characters)

  • Project ID — the project_id value

  • Client ID — the client_id value from the JSON file. This is the same numeric ID you entered in the Admin Console.

  • Token URL — the token_uri value, normally https://oauth2.googleapis.com/token

  • Scopes — space-separated list matching the scopes you authorized in the Admin Console

Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.

How the connection behaves

  • Caddi impersonates real users. A service account has no data of its own — every Workspace call acts as a specific user in your domain, and results reflect that user's permissions.

  • Impersonated users must have signed in at least once and accepted the Google Workspace Terms of Service.

  • Cloud IAM roles are irrelevant here. Workspace data access comes entirely from the domain-wide delegation grant.

  • Keys never expire by default. Rotate on a schedule: create the new key, update Caddi, disable the old key (reversible), verify, then delete it. Note that deleting a key does not revoke access tokens already issued from it — those remain valid until they expire, typically within an hour.

  • Deleting the delegation client stops the integration immediately, with no grace period.

  • Revoking access. Delete the service account key, remove the delegation grant in the Admin Console, or delete the service account.

Troubleshooting

unauthorized_client on every request

Almost always the Client ID in the Admin Console delegation grant. It must be the service account's numeric Unique ID, not its email address. Check that first, then confirm every scope Caddi uses is listed in the grant.

Invalid JWT Signature, no start line, or a PEM decoder error

The private key was pasted incorrectly. Open the JSON file in a plain-text editor and copy the private_key value exactly as it appears between the quotes, including the \n sequences and both the BEGIN and END armor lines. Don't include the surrounding JSON quotes, don't let an editor convert \n to real newlines, and watch for smart-quote autocorrect.

Key creation fails with a policy error

iam.disableServiceAccountKeyCreation is enforced on your organization — the default for organizations created on or after 3 May 2024. An Org Policy Administrator needs to grant an exception for this project.

It works for some users but not others

Those users may not have signed in and accepted the Workspace Terms of Service yet, or they may be outside the domain the delegation grant covers.

Nothing works right after setup

Delegation changes can take up to 24 hours to propagate. Wait before recreating credentials — and check whether your organization requires a second super admin to approve the grant.

A scope error on one specific operation

That scope isn't in the Admin Console delegation grant. Add it, then wait for propagation.

Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.

Automation ideas

Law Firms

Shared intake mailbox → matter creation

Caddi monitors the firm's intake address, reads new enquiries, and creates the matter and contact records — without anyone needing to connect a personal account.

Scheduled overnight filing

Caddi runs unattended overnight, files the day's correspondence to the right matter folders, and posts a summary in the morning.

Firm-wide document generation

Caddi generates documents from templates on a schedule and files them to shared Drive locations, independent of any individual's session.

RIAs

Shared operations mailbox → tracked requests

Caddi watches the operations inbox and turns client requests into tracked work items with the right owner.

Scheduled quarterly reporting

Caddi assembles and distributes client reports on a schedule, filing each to the right client folder without an advisor triggering it.

Related Articles
Did this answer your question?