Google OAUTH

Google OAuth Agent Skill

Self-hosted Google OAuth authentication for any Google API (Gmail, Calendar, Drive, Ads, etc.).

Overview

This skill provides a complete OAuth 2.0 flow for Google APIs without external dependencies like Nango. It:

• Runs a local callback server on port 3000
• Generates dynamic callback URLs for Shakudo deployments
• Handles token exchange and storage
• Supports automatic token refresh
• Works with any Google API scope

Quick Start

# 1. Set up credentials (one-time)
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"

# 2. Run OAuth flow for Gmail
cd scripts/
python auth_flow.py --scopes gmail_full

# 3. Tokens saved to .env, ready to use

Prerequisites

Python Dependencies

pip install httpx python-dotenv

Google Cloud OAuth App (One-Time Setup)

1. Go to Google Cloud Console
2. Create a project (or select existing)
3. Click Create Credentials → OAuth Client ID
4. Select Web application
5. Add redirect URI (see Callback URL below)
6. Copy the Client ID and Client Secret

Enable Required APIs

For the Google APIs you want to use:

• Gmail API
• Google Calendar API
• Google Drive API
• Google Ads API

Callback URL

The callback URL is dynamically generated based on the MY_JOB_ID environment variable (set automatically in Shakudo deployments).

Pattern: https://nextjs-{first-6-chars-of-job-id}.dev.hyperplane.dev/oauth/callback

Example: If MY_JOB_ID=abc123xyz, callback URL is:

https://nextjs-abc123.dev.hyperplane.dev/oauth/callback

For local development (no MY_JOB_ID):

https://nextjs-000000.dev.hyperplane.dev/oauth/callback

Add this URL to your Google OAuth app's authorized redirect URIs.

Supported Scopes

Custom scopes: You can also use full scope URLs directly:

python auth_flow.py --scopes "https://www.googleapis.com/auth/userinfo.email"

Environment Variables

*The scripts check GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET first, then fall back to GOOGLE_ADS_CLIENT_ID / GOOGLE_ADS_CLIENT_SECRET for compatibility with the marketing TUI.

User Experience Flow

First-Time Setup

User: "Connect my Gmail account"

Agent: "I don't see Gmail credentials configured. Let me help you set up OAuth.
        Do you have a Google Cloud OAuth Client ID and Secret?"

User: "No"

Agent: "No problem. Here's how to create one:
        1. Go to https://console.cloud.google.com/apis/credentials
        2. Create OAuth 2.0 Client ID (Web application)
        3. Add redirect URI: https://nextjs-XXXXXX.dev.hyperplane.dev/oauth/callback
        4. Copy the Client ID and Client Secret
        
        Let me know when you have them."

User: "Got it. Client ID is XXX, Secret is YYY"

Agent: [Saves credentials to .env]
       "Starting OAuth server...
        
        Please open this URL in your browser to authorize Gmail access:
        https://accounts.google.com/o/oauth2/v2/auth?client_id=...
        
        Waiting for authorization... (5 min timeout)"

[User authorizes in browser, gets redirected to callback]

Agent: "Authorization received! Exchanging for tokens...
        
        Gmail connected successfully!
        • Access token: saved (expires in 1 hour)
        • Refresh token: saved (auto-renews)
        • Scopes: gmail.readonly, gmail.send
        
        You can now ask me to read or send emails."

Subsequent Usage

User: "Check my unread emails"

Agent: [Loads tokens from .env]
       [Auto-refreshes if access token expired]
       [Calls Gmail API]
       "You have 3 unread emails:
        1. From: boss@company.com - Subject: Q1 Report
        ..."

Token Expired / Revoked

User: "Send an email"

Agent: [Detects refresh token no longer works]
       "Your Gmail authorization has expired. Let me reconnect..."
       [Restarts OAuth flow]

Script Reference

oauth_server.py

Callback server for receiving OAuth redirects.

# Start server and wait for callback
python oauth_server.py --wait --timeout 300

# Just start server (for debugging)
python oauth_server.py

Python API:

from oauth_server import OAuthServer, GOOGLE_SCOPE_PRESETS

server = OAuthServer()
if server.start():
    # Generate auth URL
    url, state = server.generate_auth_url(
        client_id="your-client-id",
        scopes=["gmail_full", "calendar"],
        access_type="offline",
        prompt="consent"
    )
    print(f"Open: {url}")
    
    # Wait for callback
    result = server.wait_for_callback(timeout=300)
    if result.success:
        print(f"Code: {result.code}")
    else:
        print(f"Error: {result.error}")
    
    server.stop()

auth_flow.py

Complete OAuth authorization flow.

# Interactive flow (recommended)
python auth_flow.py --scopes gmail_full

# Multiple scopes
python auth_flow.py --scopes gmail_full calendar drive

# Just generate URL (for manual flow)
python auth_flow.py --scopes gmail_full --url-only

# Exchange code manually
python auth_flow.py --exchange-code "4/0AY0e-g..."

# List available scope presets
python auth_flow.py --list-scopes

token_refresh.py

Token status and refresh.

# Check token status
python token_refresh.py --status

# Force refresh access token
python token_refresh.py --refresh

# Auto-refresh only if needed (silent, for scripts)
python token_refresh.py --auto

# Get valid access token (refreshes if needed)
TOKEN=$(python token_refresh.py --get-token)

Python API:

from token_refresh import get_valid_token

# Get valid access token (auto-refreshes if needed)
token = get_valid_token()
if token:
    # Use token with Google APIs
    headers = {"Authorization": f"Bearer {token}"}

Integration Examples

With google_workspace_mcp

from token_refresh import get_valid_token

# Get token for google_workspace_mcp
access_token = get_valid_token()
if not access_token:
    print("Need to run OAuth flow first")
    exit(1)

# Configure google_workspace_mcp to use this token
# (implementation depends on how you've integrated it)

With Gmail API Directly

import httpx
from token_refresh import get_valid_token

token = get_valid_token()
if not token:
    raise RuntimeError("No valid token")

async with httpx.AsyncClient() as client:
    response = await client.get(
        "https://gmail.googleapis.com/gmail/v1/users/me/messages",
        headers={"Authorization": f"Bearer {token}"},
        params={"maxResults": 10}
    )
    messages = response.json()

With Google Calendar API

import httpx
from token_refresh import get_valid_token

token = get_valid_token()

async with httpx.AsyncClient() as client:
    response = await client.get(
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        headers={"Authorization": f"Bearer {token}"},
        params={"maxResults": 10}
    )
    events = response.json()

Error Handling

Security Notes

1. Never commit credentials - Use .env files and add to .gitignore
2. Refresh tokens persist - Treat refresh tokens like passwords
3. Scope minimization - Only request scopes you need
4. Token storage - Tokens are stored in plaintext .env files
5. HTTPS callbacks - Google requires HTTPS for production callback URLs

Troubleshooting

"redirect_uri_mismatch" Error

The callback URL in your Google OAuth app doesn't match. Check:

1. Your MY_JOB_ID environment variable
2. The redirect URI in Google Cloud Console

Tokens Not Persisting

Check that:

1. .env file is writable
2. GOOGLE_OAUTH_ENV_PATH is set correctly (if using custom path)
3. No file permission issues

Auto-Refresh Not Working

1. Check you have a refresh token: python token_refresh.py --status
2. Verify client credentials are correct
3. Ensure the refresh token hasn't been revoked

Files

google-oauth/
├── SKILL.md              # This documentation
├── .env.example          # Credential template
└── scripts/
    ├── oauth_server.py   # Callback server (port 3000)
    ├── auth_flow.py      # Authorization flow
    └── token_refresh.py  # Token refresh utility