gog (Google Workspace CLI) OAuth Setup Gotchas¶
Notes¶
Summary¶
Summary¶
Setting up gog (Google Workspace CLI) against a fresh Google Cloud project on this instance hit three separate, non-obvious failure modes before working end to end. Captured here so a future re-setup (new account, new project) doesn't re-derive these from scratch.
1. OAuth consent screen defaults to "Internal" — rejects personal Gmail accounts¶
A newly created Google Cloud OAuth client's Audience defaults to Internal (Workspace-org-only). Attempting consent with a personal @gmail.com account fails with a cryptic org_internal: This client is restricted to users within its organization error page — easy to mistake for "the tab didn't open" rather than a real, completed error.
Fix: Google Cloud Console → APIs & Services → Google Auth Platform → Audience → "Make external" → choose In production (not "Testing" — Testing-mode refresh tokens for external apps expire every 7 days, forcing weekly re-auth). "In production" for an unverified personal app is fine; it just shows an "unverified app" warning during consent, not a blocker.
2. gog auth setup --login has a short-lived local callback listener¶
The standard --login flow starts a local HTTP listener for the OAuth redirect, but it can time out (authorization canceled: context deadline exceeded) before a human finishes clicking through consent — especially if there's any delay (switching windows, re-authing to the right Google account first). The browser then lands on a dead 127.0.0.1:<port>/oauth2/callback?...code=... URL with nothing listening, which looks like nothing happened.
Fix: use the remote two-step flow instead, which has no listener and no timeout:
gog auth add <email> --services <...> --remote --step 1 # prints auth URL, no listener
# open the URL, complete consent at your own pace
gog auth add <email> --services <...> --remote --step 2 --auth-url "<full pasted callback URL>"
3. Google Cloud APIs must be individually enabled per project — not all are on by default¶
Even after OAuth succeeds, individual gog commands fail with <API> is not enabled for this OAuth project until each underlying Google Cloud API is turned on for the project. On this project, Gmail API and Calendar API happened to already be enabled, but Drive, Docs, Sheets, and People (Contacts) API were not and had to be enabled manually via Console → APIs & Services → Library → [API] → Enable.
Fix: after auth succeeds, smoke-test every service you actually intend to use (gog drive ls, gog contacts list, gog sheets metadata <fake-id>, gog docs cat <fake-id>) rather than assuming auth success means everything works — a 404/not-found response on a fake ID is fine (proves the API call reached Google); an explicit "API not enabled" error is the thing to catch.
Bonus: gog me needs an extra scope not in the default service list¶
gog me (identity lookup) calls the People API people/me endpoint, which needs the profile OAuth scope — not included by any of the default --services values. Fails with 403 forbidden ... Request requires one of the following scopes: [profile] even though every other command works fine. Fix: re-run auth with --extra-scopes https://www.googleapis.com/auth/userinfo.profile --force-consent (force-consent needed because Google won't silently add a new scope to an existing grant).