Google Workspace

Connect Google Workspace

This integration talks to the Google Workspace APIs (Calendar, Gmail, Drive/Docs/Sheets, Admin Directory, People) using a Google Cloud service account with domain-wide delegation — server-to-server, no interactive sign-in. Every request impersonates a Workspace user. About 15 minutes, and you need a Workspace super-admin to authorise the delegation.

1. Create a service account + key (Google Cloud Console)

1. console.cloud.google.com → pick or create a project → APIs & Services → Enable APIs & Services and enable: Google Calendar API, Gmail API, Google Drive API, Google Docs API, Google Sheets API, Admin SDK API, People API (enable only the ones you'll use).
2. IAM & Admin → Service Accounts → Create service account. Name it (e.g. "omadia") → Done.
3. Open the service account → Keys → Add key → Create new key → JSON. A .json file downloads. From it you need two values: client_email → field Service-account email, and private_key (the long -----BEGIN PRIVATE KEY----- … block) → field Service-account private key.
4. On the service account's Details page note the Unique ID (a long number) — that is the Client ID used in step 2.

2. Authorise domain-wide delegation (Workspace Admin console)

1. admin.google.com → Security → Access and data control → API controls → Domain-wide delegation → Manage domain-wide delegation → Add new.
2. Client ID = the service account's Unique ID (step 1.4).
3. OAuth scopes = the comma-separated scope list. After install, the plugin logs the exact scopes it will request (delegated scopes (authorise these…)); paste those. The defaults are:

   https://www.googleapis.com/auth/calendar.readonly,
   https://www.googleapis.com/auth/gmail.readonly,
   https://www.googleapis.com/auth/drive.readonly,
   https://www.googleapis.com/auth/documents.readonly,
   https://www.googleapis.com/auth/spreadsheets.readonly,
   https://www.googleapis.com/auth/admin.directory.user.readonly,
   https://www.googleapis.com/auth/contacts.readonly,
   https://www.googleapis.com/auth/directory.readonly
   

   With Enable writes on, the requested set changes: add https://www.googleapis.com/auth/calendar.events, https://www.googleapis.com/auth/gmail.send, https://www.googleapis.com/auth/gmail.compose, and the FULL https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/documents and https://www.googleapis.com/auth/spreadsheets. The full Drive, Docs and Sheets scopes REPLACE their .readonly variants above (do not list both: domain-wide delegation matches scopes literally, so an un-authorised .readonly left in the request fails the whole token). The plugin logs the exact set at activation; authorise that verbatim.
4. Authorise. Delegation can take a few minutes to propagate.

3. Fill in the fields below

Field	Value
Service-account email	client_email from the JSON key
Service-account private key	private_key from the JSON key (paste the whole PEM block)
Default user	The Workspace user the integration acts as by default (e.g. an assistant mailbox)
Admin user	A super-admin's email — used for directory lookups (optional; falls back to the default user)
Surfaces	Which areas to enable (optional; default all)
Enable writes	Off = read-only; on = also calendar/gmail writes

Install — connectivity is verified in the background by minting a token for the default user (watch the plugin logs for connected or a token probe failed warning).

Troubleshooting

• unauthorized_client / 401 at the token step — the Client ID or a scope is not authorised in step 2 (every scope the plugin requests must be listed verbatim), or delegation has not propagated yet.
• 403 on a surface — that API is not enabled in the Cloud project (step 1.1), or the impersonated user lacks access.
• invalid_grant — the Default user / Admin user email does not exist in the Workspace domain, or the private key is malformed (paste the entire PEM, including the BEGIN/END lines).
• Directory returns 403 — directory reads impersonate the Admin user; it must be a real admin and admin.directory.user.readonly must be authorised.

Least privilege: enable only the surfaces you need and leave Enable writes off unless the assistant should create events or send mail.