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
5. - Choose "External" user type
6. - Fill in app name, user support email
7. - Add scopes: `gmail.modify` (or others as needed)
8. - Important: Click "PUBLISH APP" for permanent tokens (see Troubleshooting)
9. Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID
10. - Application type: Desktop app
11. - Download the JSON file

2. Configure gog

```bash 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:

```bash # 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

```bash gog gmail search 'is:unread' --max 5 --account [email protected] ```

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.

1. Solutions (choose one):
2. Publish the app (recommended):
3. - Google Cloud Console → APIs & Services → OAuth consent screen
4. - Click "PUBLISH APP" → Confirm
5. - No Google review needed for personal use
6. - Tokens become permanent

1. Add test user:
2. - OAuth consent screen → Test users → + ADD USERS
3. - Add the Gmail address you're authorizing
4. - Tokens still expire in 7 days

"Google hasn't verified this app" warning screen

1. This is normal for personal apps. Click:
2. Advanced (bottom left)
3. 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