Gmail OAuth Setup

Gmail OAuth Setup

Headless-friendly OAuth flow for Gmail API access using gog CLI.

Prerequisites

• -gog CLI installed (brew install steipete/tap/gogcli)
• -Google Cloud project with OAuth credentials (Desktop app type)
• -Gmail API enabled in the project

Quick Setup

1. Create Google Cloud Project & Credentials

1. Go to https://console.cloud.google.com

2. Create a new project (or select existing)

3. Enable Gmail API: APIs & Services → Library → search "Gmail API" → Enable

4. Configure OAuth consent screen: APIs & Services → OAuth consent screen

- Choose "External" user type

- Fill in app name, user support email

- Add scopes: gmail.modify (or others as needed)

- Important: Click "PUBLISH APP" for permanent tokens (see Troubleshooting)

5. Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID

- Application type: Desktop app

- Download the JSON file

2. Configure gog

gog auth credentials /path/to/client_secret.json
gog auth keyring file  # Use file-based keyring for headless
export GOG_KEYRING_PASSWORD="your-password"  # Add to .bashrc

3. Run Auth Flow

Run scripts/gmail-auth.sh interactively, or:

Generate URL
scripts/gmail-auth.sh --url

User opens URL, approves, copies code from localhost redirect
Exchange code (do this quickly - codes expire in minutes!)
scripts/gmail-auth.sh --exchange CODE EMAIL

4. Verify

gog gmail search 'is:unread' --max 5 --account you@gmail.com

Troubleshooting

"Access blocked: [app] has not completed the Google verification process"

Cause: App is in "Testing" mode and the Gmail account isn't a test user. Solutions (choose one):

1. Publish the app (recommended):

- Google Cloud Console → APIs & Services → OAuth consent screen

- Click "PUBLISH APP" → Confirm

- No Google review needed for personal use

- Tokens become permanent

2. Add test user:

- OAuth consent screen → Test users → + ADD USERS

- Add the Gmail address you're authorizing

- Tokens still expire in 7 days

"Google hasn't verified this app" warning screen

This is normal for personal apps. Click:

1. Advanced (bottom left)

2. Go to [app name] (unsafe)

Safe to proceed since you own the app.

Token expires in 7 days

Cause: App is in "Testing" mode. Fix: Publish the app (see above). Published apps get permanent refresh tokens.

"invalid_request" or "invalid_grant" errors

Causes:

• -Authorization code expired (they only last a few minutes)
• -Code was already used
• -Redirect URI mismatch

Fix: Generate a fresh auth URL and complete the flow quickly. Paste the code immediately after getting it.

"redirect_uri_mismatch" error

Cause: The redirect URI in the token exchange doesn't match what was used in the auth URL. Fix: This script uses http://localhost. Make sure both the auth URL and exchange use the same redirect URI.

Page hangs after approving permissions (mobile)

Cause: Browser trying to connect to localhost which doesn't exist on phone. Fix:

• -Use a desktop browser instead
• -Or tap the address bar while it's "hanging" - the URL contains the code
• -The URL will look like: http://localhost/?code=4/0ABC...

Multiple permission checkboxes causing hangs

Cause: Too many OAuth scopes requested. Fix: Use minimal scopes. gmail.modify alone is usually sufficient and shows just one permission.

Can't find project in Google Cloud Console

Cause: Signed into wrong Google account. Fix: Check which account owns the project:

• -Click profile icon (top right)
• -Switch accounts
• -Check project dropdown for each account

"invalid_request" with oob redirect (new projects)

Cause: Google deprecated urn:ietf:wg:oauth:2.0:oob for OAuth clients created after 2022. Fix: Use http://localhost redirect instead (this script's default). After approval, browser redirects to localhost with code in URL.

Scopes Reference

| Scope | Access |

|-------|--------|

| gmail.modify | Read, send, delete, manage labels (recommended) |

| gmail.readonly | Read only |

| gmail.send | Send only |

| gmail.compose | Create drafts, send |

Files

• -scripts/gmail-auth.sh — Interactive auth helper

Tips

• -Publish your app — Avoids test user limits and 7-day token expiry
• -Exchange codes quickly — They expire in minutes
• -Use desktop browser — Mobile browsers can be finicky with localhost redirects
• -One scope is enough — gmail.modify covers most use cases