gh-krishagel-geoffrey/skills/google-workspace/auth/GOOGLE_CLOUD_SETUP.md

Google Cloud Console Setup Guide

Step 1: Create Project

1. Go to Google Cloud Console
2. Sign in with your consulting account (this will own the OAuth app)
3. Click Select a project → New Project
4. Name: Geoffrey Google Workspace
5. Click Create

Step 2: Enable APIs

Navigate to APIs & Services → Library and enable each:

Required APIs

• Gmail API
• Google Calendar API
• Google Drive API
• Google Docs API
• Google Sheets API
• Google Slides API
• Google Forms API
• Google Chat API
• Tasks API
• People API (for user info)

Optional APIs

• Google Keep API (limited availability)
• Gemini API (if using AI features)

Tip: Search for each API name and click Enable

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External (unless all accounts are in same org)
3. Click Create

App Information

• App name: Geoffrey
• User support email: Your consulting email
• Developer contact: Your consulting email

Scopes

Click Add or Remove Scopes and add:

https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/presentations
https://www.googleapis.com/auth/forms.body
https://www.googleapis.com/auth/chat.messages
https://www.googleapis.com/auth/tasks
https://www.googleapis.com/auth/userinfo.email

Test Users

Add all three email addresses:

• Your PSD email
• Your personal email
• Your consulting email

Note: While in "Testing" mode, only these users can authorize.

Step 4: Create OAuth Credentials

1. Go to APIs & Services → Credentials

2. Click Create Credentials → OAuth client ID

3. Application type: Desktop app

4. Name: Geoffrey CLI

5. Click Create

6. Copy the Client ID and Client Secret

7. Add to your iCloud secrets .env file:

   ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env
   

   Add these lines:

   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   

Step 5: PSD Domain Allowlisting

Your PSD Google Workspace likely restricts third-party apps. To allow Geoffrey:

If You're a Google Admin:

1. Go to Google Admin Console
2. Navigate to Security → Access and data control → API controls
3. Click Manage Third-Party App Access
4. Click Add app → OAuth App Name Or Client ID
5. Enter your OAuth Client ID (from Step 4)
6. Select Trusted access

If You Need IT Approval:

Send this to your IT team:

Subject: Request to Allow OAuth App for Personal Productivity Tool

I need to allowlist a personal productivity app that integrates with Google Workspace.

OAuth Client ID: [YOUR_CLIENT_ID_HERE]

Requested scopes:
- Gmail (read/send)
- Calendar (read/write)
- Drive (read/write)
- Docs/Sheets/Slides (read/write)
- Tasks (read/write)

This is a local CLI tool that runs only on my machine.
No data is sent to external servers.

Please add this client ID to the trusted apps list.

Step 6: Authenticate Each Account

Once credentials are in your .env:

cd skills/google-workspace

# Install dependencies
bun install

# Authenticate each account
bun auth/oauth_setup.js psd    # Will open browser, sign in with PSD account
bun auth/oauth_setup.js kh     # Will open browser, sign in with personal account
bun auth/oauth_setup.js hrg    # Will open browser, sign in with consulting account

# After each auth, store the tokens (copy the JSON output from oauth_setup)
bun auth/token_manager.js store psd '<tokens-json-output>'
bun auth/token_manager.js store kh '<tokens-json-output>'
bun auth/token_manager.js store hrg '<tokens-json-output>'

Step 7: Verify Setup

# List stored accounts
bun auth/token_manager.js list

# Test token retrieval
bun auth/token_manager.js get psd

Troubleshooting

"Access blocked: This app's request is invalid"

• Check that redirect URI matches: http://localhost:3000/oauth2callback
• Verify OAuth consent screen is configured

"Access denied" for PSD account

• App needs to be allowlisted in PSD Google Admin
• Contact IT with the client ID

"Refresh token is null"

• Delete the app from your Google account's connected apps
• Re-run oauth_setup.js with the account
• The prompt: 'consent' should force a new refresh token

Token expires quickly

• Access tokens last 1 hour
• token_manager.js auto-refreshes using the refresh token
• Refresh tokens don't expire unless revoked

Security Notes

• Credentials stored in iCloud secrets .env (synced, but local to your devices)
• Tokens stored in macOS Keychain (encrypted)
• Each account has its own isolated tokens
• Revoke access anytime from Google Account → Security → Third-party apps