Google Workspace APIs skill for Codex

Done well means: the integration authenticates as the right principal for the job, requests the narrowest scopes that work, holds no long-lived key file if it can avoid one, and survives quota errors with backoff instead of crashing.

Choose the principal

Situation	Principal	Notes
A person runs a tool on their own data	User OAuth (installed app or web flow)	Refresh token per user; consent screen required
SaaS product acting for many customers’ users	User OAuth, web flow, access_type=offline	Sensitive/restricted scopes need Google verification
Backend job on files/calendars it owns or that are shared to it	Service account, no delegation	Lives outside any user; share resources to its email
Backend job acting as users of one Workspace domain	Service account + domain-wide delegation (DWD)	A super admin authorises client ID + scopes
Admin SDK (users, groups, devices)	DWD impersonating an admin, or admin OAuth	Directory API needs an admin identity
Public data only (no user data)	API key	Never for Workspace user data

Ask the user which of these applies when it is not obvious. DWD is powerful: it can read every mailbox for the granted scopes. Do not propose it when per-user OAuth would do.

Before writing code

- [ ] Read AGENTS.md for secret handling and the existing Google client library
- [ ] Identify the Cloud project; enable each API (gcloud services enable drive.googleapis.com gmail.googleapis.com)
- [ ] Pick the principal (table above) and the exact scopes (table below)
- [ ] OAuth: configure the consent screen (Internal for single-domain tools, External otherwise)
- [ ] DWD: get the service account's numeric client ID for the admin to authorise
- [ ] Decide where tokens/keys live (secret manager, not the repo)

gcloud and every API call need network; in a Codex sandbox with network off, prepare code and commands and ask the user to run or approve them.

Scopes: narrowest that works

Need	Prefer	Avoid unless required
Files the app creates or the user picks	drive.file (non-sensitive)	drive (restricted)
Read Drive metadata	drive.metadata.readonly	drive.readonly
Send mail only	gmail.send (sensitive)	gmail.modify, mail.google.com
Read mail	gmail.readonly (restricted)	mail.google.com (full, incl. delete)
Calendar events	calendar.events	calendar
Sheets the app opens via picker	drive.file + Sheets API	spreadsheets on all sheets
Directory users read	admin.directory.user.readonly	admin.directory.user

All scopes are prefixed https://www.googleapis.com/auth/. Restricted scopes (most of Gmail, full Drive) require an annual third-party security assessment for External apps. In External apps left in “Testing” status, refresh tokens expire after 7 days: that, not a bug, is the usual cause of weekly invalid_grant.

User OAuth (Python)

from pathlib import Path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/drive.file"]
TOKEN = Path("~/.config/mytool/token.json").expanduser()   # outside the repo

def creds():
    c = Credentials.from_authorized_user_file(TOKEN, SCOPES) if TOKEN.exists() else None
    if c and c.expired and c.refresh_token:
        c.refresh(Request())
    elif not c or not c.valid:
        c = InstalledAppFlow.from_client_secrets_file("client_secret.json", SCOPES).run_local_server(port=0)
    TOKEN.parent.mkdir(parents=True, exist_ok=True)
    TOKEN.write_text(c.to_json())
    return c

drive = build("drive", "v3", credentials=creds(), cache_discovery=False)

Web apps: use the authorization-code flow with access_type=offline and prompt=consent only on first connect (forcing consent every time issues new refresh tokens and hits the per-client token cap). Store refresh tokens encrypted per user; handle revocation by asking the user to reconnect.

Service account with domain-wide delegation

from google.oauth2 import service_account
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/calendar.events"]
base = service_account.Credentials.from_service_account_file("/run/secrets/sa.json", scopes=SCOPES)
as_user = base.with_subject("[email protected]")            # impersonate this Workspace user
cal = build("calendar", "v3", credentials=as_user, cache_discovery=False)

Admin side (super admin, Admin console -> Security -> Access and data control -> API controls -> Domain-wide delegation): add the service account’s numeric client ID and the exact scope list. The scopes in code must be a subset of the authorised list or token exchange fails with unauthorized_client. Changes can take minutes to propagate.

Keyless: no JSON key at all

Many organisations block key creation (iam.disableServiceAccountKeyCreation). On GCP or with workload identity federation, sign the DWD assertion through the IAM Credentials API instead:

import google.auth
from google.auth import iam
from google.auth.transport.requests import Request
from google.oauth2 import service_account

SA = "[email protected]"
source, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
signer = iam.Signer(Request(), source, SA)
creds = service_account.Credentials(
    signer=signer, service_account_email=SA,
    token_uri="https://oauth2.googleapis.com/token",
    scopes=SCOPES, subject="[email protected]",
)

The runtime identity needs roles/iam.serviceAccountTokenCreator on that service account.

Node (googleapis)

import { google } from "googleapis";

const auth = new google.auth.JWT({
  keyFile: process.env.GOOGLE_SA_KEY_FILE,
  scopes: ["https://www.googleapis.com/auth/admin.directory.user.readonly"],
  subject: "[email protected]",
});
const admin = google.admin({ version: "directory_v1", auth });
const { data } = await admin.users.list({ customer: "my_customer", maxResults: 200 });

Quotas, batching, partial responses

• Errors to retry with exponential backoff and jitter: 429, 500, 503, and 403 with reason rateLimitExceeded or userRateLimitExceeded. Do not retry 403 insufficientPermissions or accessNotConfigured.
• Quotas are per project per minute and often per user per minute; spreading load across impersonated users does not raise the project limit.
• Request only needed fields: fields="nextPageToken, files(id, name, modifiedTime)".
• Batch HTTP requests (up to 100 calls per batch in most APIs, fewer for Gmail in practice) cut round trips but each inner call still counts against quota.
• Python’s HttpRequest.execute(num_retries=5) adds backoff for retryable errors.

Error decoder

Error	Usual cause	Fix
invalid_grant	Refresh token revoked or expired (Testing status, user removed access, password change on Gmail scopes); clock skew for JWT	Re-consent; publish the app; sync time
unauthorized_client	DWD not set or scopes in code exceed the authorised list	Match scopes exactly in Admin console
403 accessNotConfigured	API not enabled in the project that owns the credentials	Enable the API, wait a few minutes
403 insufficientPermissions	Token lacks the scope	Re-consent with the scope
404 on a known file/calendar	Service account (not impersonating) has no access	Share to the SA email or use DWD
admin_policy_enforced	Workspace admin blocks the app or scope	Admin must trust the app in API controls

Gotchas

• A service account is not a Workspace user: it has no Gmail mailbox and, without DWD, sees nothing in users’ Drives or calendars.
• with_subject must be a real user in the domain; groups and aliases fail.
• Consumer @gmail.com accounts cannot be impersonated; DWD is Workspace-only.
• Do not commit client_secret.json, token.json or service account keys; add them to .gitignore and scan before committing.
• Apps Script is often the simpler answer for in-domain automations owned by one team.

Verification

• Print the token’s granted scopes (creds.scopes after refresh, or call https://oauth2.googleapis.com/tokeninfo?access_token=...) and compare with intent.
• Make one read call as the intended principal and log who it ran as (e.g. Drive about.get with fields="user").
• Force a refresh (expire the cached token) and confirm the job still runs unattended.

For Drive specifics use $google-drive-api; for Gmail sync and push use $gmail-api.