Google Workspace — auth + calling Gmail/Drive/Calendar/Sheets
This skill owns one layer: authenticating to and calling the four Google
Workspace REST APIs from server-side code. Everything here is service-account
/ machine auth — if a real user must click "Allow", that is interactive OAuth and
out of scope.
Where the neighbouring layers live:
| Not this skill |
Goes to |
This skill's slice |
| SMTP/provider choice, transactional/marketing sends |
email-connector |
Gmail-the-API inside a Workspace mailbox |
| SPF/DKIM, inbox placement |
email-deliverability |
— |
| Availability search, booking-link UX, timezone-as-a-feature |
calendar-scheduling |
Raw Calendar event CRUD underneath |
| Sheet data modeling, formulas, pivots |
spreadsheet-ops |
Sheets API read/write transport |
| Doc/PDF parsing, extraction, OCR |
document-processing |
Drive as storage transport (upload/download/move/permissions) |
| Chaining several connectors into one flow |
automation-flows |
The individual Google calls |
| Notion as the backend / generic REST wrapping |
notion-connector, api-connector-builder |
— |
| Receiving Gmail/Drive push notifications |
webhooks |
— |
Pick your auth mode
Choose first — it dictates scopes, the Admin-console step, and the client build.
| Situation |
Mode |
Why |
| App owns the data (its own Drive folder, its own calendar, a shared drive it was added to) |
Service account, no delegation |
The SA is its own identity; no need to act as a human. Simplest, no Admin step. |
Must act AS each Workspace user (send from ops@acme.com, read their inbox/calendar) |
Service account + domain-wide delegation + subject |
Gmail has no "shared mailbox via SA" — to touch a user's mail/calendar you impersonate them. Requires a Workspace admin to authorize the SA. |
| Code runs on GCP (Cloud Run, GKE, Functions) or CI with WIF |
Keyless: Application Default Credentials / Workload Identity Federation |
No long-lived key file to leak or rotate. The runtime mints short-lived tokens. Always prefer this when the platform supports it. |
Rule: never reach for domain-wide delegation if app-owned resources suffice.
DWD lets the SA impersonate anyone in the org for the granted scopes — it is a
large blast radius. Use it only when you genuinely must act as the user.
Setup checklist
Do these in order. references/auth-setup.md has the full Cloud + Admin
click-path, the scope catalog, DWD authorization, keyless WIF/ADC, and a longer
troubleshooting matrix.
- Enable the APIs you will call in the Cloud console (Gmail, Drive,
Calendar, Sheets) for the project. A disabled API returns
403 regardless of
scopes.
- Create the service account in IAM & Admin → Service Accounts. For keyless
you stop here and attach the SA to the runtime; for a key you create a JSON
key (and treat it like a password — see Security).
- Decide scopes (next section) — the exact scope strings you will request.
- Authorize DWD only if impersonating. In the Admin console →
Security → Access and data control → API controls → Manage Domain Wide
Delegation, add the SA's client ID (the numeric
client_id, not the
email) plus the exact comma-separated scope list. A scope requested in
code but not authorized here is the #1 cause of unauthorized_client.
Scopes: least privilege
Request the narrowest scope that does the job. Broad scopes also force a stricter
Google verification review and widen what a leaked key can touch.
# Bad — full read/write to ALL of the user's Drive
https://www.googleapis.com/auth/drive
# Good — only files this app created or was explicitly shared
https://www.googleapis.com/auth/drive.file
| Task |
Scope |
Note |
| Send mail only |
gmail.send |
Cannot read the inbox — ideal for notifications. |
| Read mail |
gmail.readonly |
Read, no modify/delete. |
| Modify labels/state |
gmail.modify |
Avoid full mail.google.com unless you truly need delete + settings. |
| App-created Drive files |
drive.file |
Cannot see the user's other files — smallest footprint. |
| Read all Drive |
drive.readonly |
Prefer over full drive. |
| Calendar events |
calendar.events |
Narrower than full calendar. |
| Read/write Sheets |
spreadsheets |
Use spreadsheets.readonly if you only read. |
Build the authed client
Node uses googleapis (latest 173.x, maintenance mode — bugs/security only) with
google-auth-library (10.6.2). Python uses google-auth +
google-api-python-client. The impersonation line is the subject / with_subject.
// Node — service account, optionally impersonating a Workspace user.
import { google } from 'googleapis';
const auth = new google.auth.JWT({
email: process.env.SA_CLIENT_EMAIL,
key: process.env.SA_PRIVATE_KEY.replace(/\\n/g, '\n'), // from secret mgr, never a file in the repo
scopes: ['https://www.googleapis.com/auth/gmail.send'],
subject: 'ops@acme.com', // omit this line for app-owned (no-delegation) mode
});
const gmail = google.gmail({ version: 'v1', auth });
// Node — keyless on GCP (Cloud Run / GKE / CI with WIF). No key in code at all.
import { google } from 'googleapis';
const auth = new google.auth.GoogleAuth({
scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
});
const sheets = google.sheets({ version: 'v4', auth });
# Python — service account from credentials, impersonating a user.
from google.oauth2 import service_account
from googleapiclient.discovery import build
SCOPES = ["https://www.googleapis.com/auth/gmail.send"]
creds = service_account.Credentials.from_service_account_info(
sa_info, scopes=SCOPES # sa_info loaded from secret mgr, not a tracked file
).with_subject("ops@acme.com") # drop .with_subject(...) for app-owned mode
gmail = build("gmail", "v1", credentials=creds, cache_discovery=False)
Per-API recipes (short)
Copy-paste-ready minimums. Longer recipes (raw MIME with attachments, resumable
uploads, batchUpdate, recurring/timezone-correct events) are in
references/api-recipes.md.
// Gmail: send. Body must be base64url-encoded RFC 822 (note -_ , no padding).
const raw = Buffer.from(
'To: a@acme.com\r\nSubject: Report\r\n\r\nHello.'
).toString('base64url');
await gmail.users.messages.send({ userId: 'me', requestBody: { raw } });
// Drive: create a file, then grant read to one person (least-privilege share).
const file = await drive.files.create({
requestBody: { name: 'report.pdf' },
media: { mimeType: 'application/pdf', body: stream },
fields: 'id', // partial response — ask only for what you use
});
await drive.permissions.create({
fileId: file.data.id,
requestBody: { role: 'reader', type: 'user', emailAddress: 'a@acme.com' },
});
# Calendar: insert an event (always send explicit IANA timeZone).
event = {
"summary": "Sync",
"start": {"dateTime": "2026-06-10T10:00:00", "timeZone": "Europe/Andorra"},
"end": {"dateTime": "2026-06-10T10:30:00", "timeZone": "Europe/Andorra"},
}
cal.events().insert(calendarId="primary", body=event).execute()
# Sheets: write a range. Use values.batchUpdate to write many ranges in one call.
sheets.spreadsheets().values().update(
spreadsheetId=SID, range="Sheet1!A2",
valueInputOption="USER_ENTERED",
body={"values": [["2026-06-02", 1290]]},
).execute()
Stay under quota
The per-user ceiling is the one that bites a cron looping over a mailbox.
- Gmail: 1.2M units/min per project, 6,000 units/min per user, 80M
units/day. Costs:
messages.send 100, messages.get 20, messages.list 5,
messages.modify 5, drafts.create 10. Hard cap 500 recipients/message.
- Drive: 1M units/min per project, 325,000 units/min per user, 1 TB/day
egress.
- Sheets: read and write each 300/min per project, 60/min per user; 429
on overage; 180s request timeout; keep payloads under ~2 MB.
- Policy shift: as of 2026-05-01 Google updated Workspace quota policy —
projects active Nov 2025–Apr 2026 keep legacy quotas, new projects get the new
model, and overage will start incurring Cloud billing charges later in 2026.
Treat quota as a cost line, not a free ceiling.
Three habits keep you under it:
fields partial responses — ask only for the fields you read; smaller
responses, lower cost, faster.
- Batch — Sheets
values.batchUpdate, Gmail batch requests, Drive batch —
one call instead of N cuts per-user request count directly.
- Exponential backoff with jitter on
403 rateLimitExceeded and 429 —
retrying immediately just burns more quota.
# Backoff: min((2^n) + random_ms, max_backoff). Cap 32–64s. Jitter avoids
# thundering-herd retries syncing up.
import random, time
from googleapiclient.errors import HttpError
def with_backoff(call, max_retries=6, max_backoff=64):
for n in range(max_retries):
try:
return call()
except HttpError as e:
if e.resp.status not in (403, 429) or n == max_retries - 1:
raise
time.sleep(min((2 ** n) + random.random(), max_backoff))
Security rules
- Never commit the SA key JSON. It is a long-lived bearer credential — a
committed
service_account.json is game over. Add *.json SA patterns to
.gitignore; the verify.sh here flags tracked keys.
- Prefer keyless. A leaked key is the single most common Workspace credential
compromise. On GCP/CI use ADC or Workload Identity Federation so there is no
file to leak. If you must use a key, store it in a secret manager
(env-injected, not a file beside the code) and rotate it.
- Least scope. A leaked
drive.file key sees app files; a leaked full
drive key sees everything. The scope IS the blast radius.
- Map the error before you change anything:
| Error |
Likely cause |
Fix |
unauthorized_client |
SA client ID / scope not authorized for DWD |
Add the client ID + exact scopes in Admin console Manage DWD |
403 insufficient permissions |
Scope too narrow, or API not enabled |
Widen to the right scope (still least), enable the API |
403 rateLimitExceeded / 429 |
Per-user or per-project quota hit |
Exponential backoff + jitter; batch; spread load |
400 failedPrecondition on impersonation |
subject set but DWD not configured |
Either remove subject (app-owned) or finish DWD setup |
invalid_grant |
Clock skew or stale/rotated key |
Sync clock; re-issue the key |
Anti-patterns
| Anti-pattern |
Why it breaks |
Do instead |
Committing service_account.json to the repo |
Long-lived key in git history = full compromise; can't un-leak |
Keyless ADC/WIF, or key in a secret manager + .gitignore |
Requesting auth/drive / mail.google.com "to be safe" |
Max blast radius, stricter Google review, more to leak |
Narrowest scope: drive.file, gmail.send, spreadsheets.readonly |
Using DWD subject for app-owned data |
Impersonating users when the SA could own the resource — needless blast radius + an Admin dependency |
Drop subject; let the SA own the folder/calendar/shared drive |
Looping messages.send/values.update per row with no backoff |
Trips the 6k/min (Gmail) or 60/min (Sheets) per-user cap → 429 storm |
Batch (values.batchUpdate) + exponential backoff with jitter |
Reading whole resources without fields |
Bigger payloads, higher quota cost, slower |
Request only the fields you use (fields: 'id') |
| Hardcoding the private key inline in source |
Can't rotate, leaks via logs/screenshots/history |
Inject from env/secret manager; \n-unescape at load |
Pasting raw text into Gmail raw |
API needs base64url RFC 822, not plain text → 400 |
Build a MIME message, base64url-encode it |
Before this connector ships, run the secret-handling and key-rotation pass in
../security-audit/SKILL.md.
1---2name: google-workspace3description: "Use when server-side code reads or writes Gmail, Drive, Calendar, or Sheets with a GCP service account and no human in the OAuth loop: picking the auth mode (app-owned vs domain-wide delegation vs keyless), scoping to least privilege, building the authed Node/Python client, staying under per-user quota, and debugging unauthorized_client / 403 / 429. NOT SMTP providers or deliverability (that is `email-connector`), NOT slot-finding and booking UX (that is `calendar-scheduling`)."4tags: [google-workspace, gmail-api, drive-api, calendar-api, sheets-api, service-account, domain-wide-delegation, oauth-scopes]5recommends: [email-connector, calendar-scheduling, spreadsheet-ops, document-processing, automation-flows, security-audit, webhooks]6origin: risco7metadata:8 source: https://skillmd.com/skills/ericrisco/google-workspace9---1011# Google Workspace — auth + calling Gmail/Drive/Calendar/Sheets1213This skill owns one layer: **authenticating to and calling the four Google14Workspace REST APIs from server-side code.** Everything here is service-account15/ machine auth — if a real user must click "Allow", that is interactive OAuth and16out of scope.1718Where the neighbouring layers live:1920| Not this skill | Goes to | This skill's slice |21|---|---|---|22| SMTP/provider choice, transactional/marketing sends | `email-connector` | Gmail-the-API inside a Workspace mailbox |23| SPF/DKIM, inbox placement | `email-deliverability` | — |24| Availability search, booking-link UX, timezone-as-a-feature | `calendar-scheduling` | Raw Calendar event CRUD underneath |25| Sheet data modeling, formulas, pivots | `spreadsheet-ops` | Sheets API read/write transport |26| Doc/PDF parsing, extraction, OCR | `document-processing` | Drive as storage transport (upload/download/move/permissions) |27| Chaining several connectors into one flow | `automation-flows` | The individual Google calls |28| Notion as the backend / generic REST wrapping | `notion-connector`, `api-connector-builder` | — |29| Receiving Gmail/Drive push notifications | `webhooks` | — |3031## Pick your auth mode3233Choose first — it dictates scopes, the Admin-console step, and the client build.3435| Situation | Mode | Why |36|---|---|---|37| App owns the data (its own Drive folder, its own calendar, a shared drive it was added to) | Service account, **no** delegation | The SA is its own identity; no need to act as a human. Simplest, no Admin step. |38| Must act AS each Workspace user (send from `ops@acme.com`, read their inbox/calendar) | Service account + **domain-wide delegation** + `subject` | Gmail has no "shared mailbox via SA" — to touch a user's mail/calendar you impersonate them. Requires a Workspace admin to authorize the SA. |39| Code runs on GCP (Cloud Run, GKE, Functions) or CI with WIF | **Keyless**: Application Default Credentials / Workload Identity Federation | No long-lived key file to leak or rotate. The runtime mints short-lived tokens. Always prefer this when the platform supports it. |4041Rule: **never reach for domain-wide delegation if app-owned resources suffice.**42DWD lets the SA impersonate *anyone* in the org for the granted scopes — it is a43large blast radius. Use it only when you genuinely must act as the user.4445## Setup checklist4647Do these in order. `references/auth-setup.md` has the full Cloud + Admin48click-path, the scope catalog, DWD authorization, keyless WIF/ADC, and a longer49troubleshooting matrix.50511. **Enable the APIs** you will call in the Cloud console (Gmail, Drive,52 Calendar, Sheets) for the project. A disabled API returns `403` regardless of53 scopes.542. **Create the service account** in IAM & Admin → Service Accounts. For keyless55 you stop here and attach the SA to the runtime; for a key you create a JSON56 key (and treat it like a password — see Security).573. **Decide scopes** (next section) — the exact scope *strings* you will request.584. **Authorize DWD only if impersonating.** In the Admin console →59 Security → Access and data control → API controls → **Manage Domain Wide60 Delegation**, add the SA's **client ID** (the numeric `client_id`, not the61 email) plus the **exact** comma-separated scope list. A scope requested in62 code but not authorized here is the #1 cause of `unauthorized_client`.6364## Scopes: least privilege6566Request the narrowest scope that does the job. Broad scopes also force a stricter67Google verification review and widen what a leaked key can touch.6869```text70# Bad — full read/write to ALL of the user's Drive71https://www.googleapis.com/auth/drive7273# Good — only files this app created or was explicitly shared74https://www.googleapis.com/auth/drive.file75```7677| Task | Scope | Note |78|---|---|---|79| Send mail only | `gmail.send` | Cannot read the inbox — ideal for notifications. |80| Read mail | `gmail.readonly` | Read, no modify/delete. |81| Modify labels/state | `gmail.modify` | Avoid full `mail.google.com` unless you truly need delete + settings. |82| App-created Drive files | `drive.file` | Cannot see the user's other files — smallest footprint. |83| Read all Drive | `drive.readonly` | Prefer over full `drive`. |84| Calendar events | `calendar.events` | Narrower than full `calendar`. |85| Read/write Sheets | `spreadsheets` | Use `spreadsheets.readonly` if you only read. |8687## Build the authed client8889Node uses `googleapis` (latest 173.x, maintenance mode — bugs/security only) with90`google-auth-library` (10.6.2). Python uses `google-auth` +91`google-api-python-client`. The impersonation line is the `subject` / `with_subject`.9293```javascript94// Node — service account, optionally impersonating a Workspace user.95import { google } from 'googleapis';9697const auth = new google.auth.JWT({98 email: process.env.SA_CLIENT_EMAIL,99 key: process.env.SA_PRIVATE_KEY.replace(/\\n/g, '\n'), // from secret mgr, never a file in the repo100 scopes: ['https://www.googleapis.com/auth/gmail.send'],101 subject: 'ops@acme.com', // omit this line for app-owned (no-delegation) mode102});103const gmail = google.gmail({ version: 'v1', auth });104```105106```javascript107// Node — keyless on GCP (Cloud Run / GKE / CI with WIF). No key in code at all.108import { google } from 'googleapis';109const auth = new google.auth.GoogleAuth({110 scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],111});112const sheets = google.sheets({ version: 'v4', auth });113```114115```python116# Python — service account from credentials, impersonating a user.117from google.oauth2 import service_account118from googleapiclient.discovery import build119120SCOPES = ["https://www.googleapis.com/auth/gmail.send"]121creds = service_account.Credentials.from_service_account_info(122 sa_info, scopes=SCOPES # sa_info loaded from secret mgr, not a tracked file123).with_subject("ops@acme.com") # drop .with_subject(...) for app-owned mode124gmail = build("gmail", "v1", credentials=creds, cache_discovery=False)125```126127## Per-API recipes (short)128129Copy-paste-ready minimums. Longer recipes (raw MIME with attachments, resumable130uploads, `batchUpdate`, recurring/timezone-correct events) are in131`references/api-recipes.md`.132133```javascript134// Gmail: send. Body must be base64url-encoded RFC 822 (note -_ , no padding).135const raw = Buffer.from(136 'To: a@acme.com\r\nSubject: Report\r\n\r\nHello.'137).toString('base64url');138await gmail.users.messages.send({ userId: 'me', requestBody: { raw } });139```140141```javascript142// Drive: create a file, then grant read to one person (least-privilege share).143const file = await drive.files.create({144 requestBody: { name: 'report.pdf' },145 media: { mimeType: 'application/pdf', body: stream },146 fields: 'id', // partial response — ask only for what you use147});148await drive.permissions.create({149 fileId: file.data.id,150 requestBody: { role: 'reader', type: 'user', emailAddress: 'a@acme.com' },151});152```153154```python155# Calendar: insert an event (always send explicit IANA timeZone).156event = {157 "summary": "Sync",158 "start": {"dateTime": "2026-06-10T10:00:00", "timeZone": "Europe/Andorra"},159 "end": {"dateTime": "2026-06-10T10:30:00", "timeZone": "Europe/Andorra"},160}161cal.events().insert(calendarId="primary", body=event).execute()162```163164```python165# Sheets: write a range. Use values.batchUpdate to write many ranges in one call.166sheets.spreadsheets().values().update(167 spreadsheetId=SID, range="Sheet1!A2",168 valueInputOption="USER_ENTERED",169 body={"values": [["2026-06-02", 1290]]},170).execute()171```172173## Stay under quota174175The per-user ceiling is the one that bites a cron looping over a mailbox.176177- **Gmail:** 1.2M units/min per project, **6,000 units/min per user**, 80M178 units/day. Costs: `messages.send` 100, `messages.get` 20, `messages.list` 5,179 `messages.modify` 5, `drafts.create` 10. Hard cap **500 recipients/message**.180- **Drive:** 1M units/min per project, **325,000 units/min per user**, 1 TB/day181 egress.182- **Sheets:** read and write each 300/min per project, **60/min per user**; 429183 on overage; 180s request timeout; keep payloads under ~2 MB.184- **Policy shift:** as of 2026-05-01 Google updated Workspace quota policy —185 projects active Nov 2025–Apr 2026 keep legacy quotas, new projects get the new186 model, and overage will start incurring Cloud billing charges later in 2026.187 Treat quota as a cost line, not a free ceiling.188189Three habits keep you under it:1901911. **`fields` partial responses** — ask only for the fields you read; smaller192 responses, lower cost, faster.1932. **Batch** — Sheets `values.batchUpdate`, Gmail batch requests, Drive batch —194 one call instead of N cuts per-user request count directly.1953. **Exponential backoff with jitter** on `403 rateLimitExceeded` and `429` —196 retrying immediately just burns more quota.197198```python199# Backoff: min((2^n) + random_ms, max_backoff). Cap 32–64s. Jitter avoids200# thundering-herd retries syncing up.201import random, time202from googleapiclient.errors import HttpError203204def with_backoff(call, max_retries=6, max_backoff=64):205 for n in range(max_retries):206 try:207 return call()208 except HttpError as e:209 if e.resp.status not in (403, 429) or n == max_retries - 1:210 raise211 time.sleep(min((2 ** n) + random.random(), max_backoff))212```213214## Security rules215216- **Never commit the SA key JSON.** It is a long-lived bearer credential — a217 committed `service_account.json` is game over. Add `*.json` SA patterns to218 `.gitignore`; the `verify.sh` here flags tracked keys.219- **Prefer keyless.** A leaked key is the single most common Workspace credential220 compromise. On GCP/CI use ADC or Workload Identity Federation so there is no221 file to leak. If you must use a key, store it in a secret manager222 (env-injected, not a file beside the code) and rotate it.223- **Least scope.** A leaked `drive.file` key sees app files; a leaked full224 `drive` key sees everything. The scope IS the blast radius.225- **Map the error before you change anything:**226227| Error | Likely cause | Fix |228|---|---|---|229| `unauthorized_client` | SA client ID / scope not authorized for DWD | Add the client ID + **exact** scopes in Admin console Manage DWD |230| `403 insufficient permissions` | Scope too narrow, or API not enabled | Widen to the right scope (still least), enable the API |231| `403 rateLimitExceeded` / `429` | Per-user or per-project quota hit | Exponential backoff + jitter; batch; spread load |232| `400 failedPrecondition` on impersonation | `subject` set but DWD not configured | Either remove `subject` (app-owned) or finish DWD setup |233| `invalid_grant` | Clock skew or stale/rotated key | Sync clock; re-issue the key |234235## Anti-patterns236237| Anti-pattern | Why it breaks | Do instead |238|---|---|---|239| Committing `service_account.json` to the repo | Long-lived key in git history = full compromise; can't un-leak | Keyless ADC/WIF, or key in a secret manager + `.gitignore` |240| Requesting `auth/drive` / `mail.google.com` "to be safe" | Max blast radius, stricter Google review, more to leak | Narrowest scope: `drive.file`, `gmail.send`, `spreadsheets.readonly` |241| Using DWD `subject` for app-owned data | Impersonating users when the SA could own the resource — needless blast radius + an Admin dependency | Drop `subject`; let the SA own the folder/calendar/shared drive |242| Looping `messages.send`/`values.update` per row with no backoff | Trips the 6k/min (Gmail) or 60/min (Sheets) per-user cap → 429 storm | Batch (`values.batchUpdate`) + exponential backoff with jitter |243| Reading whole resources without `fields` | Bigger payloads, higher quota cost, slower | Request only the fields you use (`fields: 'id'`) |244| Hardcoding the private key inline in source | Can't rotate, leaks via logs/screenshots/history | Inject from env/secret manager; `\n`-unescape at load |245| Pasting raw text into Gmail `raw` | API needs base64url RFC 822, not plain text → 400 | Build a MIME message, `base64url`-encode it |246247Before this connector ships, run the secret-handling and key-rotation pass in248`../security-audit/SKILL.md`.