Google Workspace

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:

Pick your auth mode

Choose first — it dictates scopes, the Admin-console step, and the client build.

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.

1. 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.
2. 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).
3. Decide scopes (next section) — the exact scope strings you will request.
4. 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

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:

1. fields partial responses — ask only for the fields you read; smaller responses, lower cost, faster.
2. Batch — Sheets values.batchUpdate, Gmail batch requests, Drive batch — one call instead of N cuts per-user request count directly.
3. 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:

Anti-patterns

Before this connector ships, run the secret-handling and key-rotation pass in ../secure-coding/SKILL.md.