scripts/SETUP_GUIDE.md

OAuth Token Refresh Setup Guide

This guide will help you set up automated daily OAuth token refresh for VoiceCal.ai.

Quick Summary

Problem: Google OAuth tokens in testing mode expire after 24 hours.

Solution: Automatically refresh tokens daily using:

1. Local Cron Job (runs on your machine)
2. GitHub Actions (runs in the cloud)

Prerequisites

You've already completed this! ✅

• ✅ Manually authenticated via http://localhost:8080/auth/login
• ✅ Fresh refresh token saved to .env
• ✅ Tested refresh script successfully

---

Option 1: Cron Job (Local Machine)

Runs on your Mac daily at noon

Setup

# Run the automated setup script
./scripts/setup_cron.sh

This will:

• Add a cron job that runs daily at 12:00 PM
• Log output to logs/cron.log
• Send email notification if refresh fails

Verify

# List current cron jobs
crontab -l

# Check logs
tail -f logs/cron.log

Manual Test

# Test the cron job command manually
cd /Users/petergits/dev/voiceCal-ai-v3 && python3 scripts/refresh_token_only.py --notify-email pgits.job@gmail.com

Remove

# Edit crontab
crontab -e

# Delete the line containing 'refresh_token_only.py'

---

Option 2: GitHub Actions (Cloud-based)

Runs in GitHub's cloud daily at noon UTC

Setup

1. Push the workflow file (already created):

   git add .github/workflows/refresh-oauth-tokens.yml
   git commit -m "Add OAuth token refresh workflow"
   git push
   

2. Add GitHub Secrets (go to your repository → Settings → Secrets and variables → Actions):

   Required secrets:

   GOOGLE_CLIENT_ID          = (from your .env file)
   GOOGLE_CLIENT_SECRET      = (from your .env file)
   GOOGLE_REFRESH_TOKEN      = (from your .env file)
   HF_TOKEN                  = (your HuggingFace token)
   

   Optional (for email notifications):

   SMTP_HOST                 = smtp.gmail.com
   SMTP_PORT                 = 587
   SMTP_USERNAME             = pgits.job@gmail.com
   SMTP_PASSWORD             = (your Gmail app password)
   NOTIFY_EMAIL              = pgits.job@gmail.com
   

3. Test the workflow:

   • Go to your repository → Actions tab
   • Click "Refresh OAuth Tokens" workflow
   • Click "Run workflow" → "Run workflow"
   • Watch it run and verify success ✅

Verify

• Go to repository → Actions tab
• Check workflow runs daily at noon UTC
• View logs for each run
• Failed runs will upload logs as artifacts

---

Which Option to Choose?

Use Cron Job if:

• ✅ Your Mac is always running (or on at noon daily)
• ✅ You want local control
• ✅ You don't want to depend on GitHub

Use GitHub Actions if:

• ✅ You want it to run even when your Mac is off
• ✅ You prefer cloud-based automation
• ✅ You want workflow run history in GitHub

Use Both if:

• ✅ You want redundancy (if one fails, the other succeeds)
• ⚠️ Tokens refresh every hour, so both running is fine

---

Troubleshooting

"Token has been expired or revoked"

Cause: Your refresh token is older than 7 days (testing mode limit)

Solution: Re-authenticate manually:

# Start local server
uvicorn app.api.main:app --reload --port 8080

# Visit in browser
http://localhost:8080/auth/login

# Complete OAuth flow
# New refresh token will be saved automatically

"Failed to refresh token: 400 Bad Request"

Cause: Invalid client ID, client secret, or refresh token

Solution: Check .env file has correct values:

grep -E "GOOGLE_CLIENT_ID|GOOGLE_CLIENT_SECRET|GOOGLE_REFRESH_TOKEN" .env

Cron job not running

Check if cron service is running:

# macOS
sudo launchctl list | grep cron

# View cron logs
log show --predicate 'process == "cron"' --last 1h

Verify cron job is installed:

crontab -l

GitHub Actions not running

Check workflow file:

# Validate YAML syntax
cat .github/workflows/refresh-oauth-tokens.yml

Check repository settings:

• Settings → Actions → General
• Ensure "Allow all actions" is enabled

---

Manual Refresh Anytime

# Local refresh
python3 scripts/refresh_token_only.py

# With email notification
python3 scripts/refresh_token_only.py --notify-email your@email.com

# Verbose output for debugging
python3 scripts/refresh_token_only.py --verbose

---

Monitoring

View Recent Logs

# Latest refresh log
ls -t logs/token_refresh_*.log | head -1 | xargs cat

# Cron job log
tail -f logs/cron.log

Check Token Expiry

grep GOOGLE_TOKEN_EXPIRY .env

Test Refresh Manually

# Run refresh script
python3 scripts/refresh_token_only.py

# Should see:
# ✅ SUCCESS
# Status: ✅ SUCCESS

---

Production Mode (Future)

When your OAuth app goes to production mode:

• Refresh tokens don't expire every 7 days
• You can reduce refresh frequency (weekly instead of daily)
• Update cron schedule: 0 12 * * 0 (weekly on Sunday)
• Update GitHub Actions cron: 0 12 * * 0

---

Questions?

• Cron not working? Check logs/cron.log
• GitHub Actions failing? Check Actions tab → Workflow run → Logs
• Need help? Contact support or file an issue

---

You're all set! 🎉

Your OAuth tokens will now refresh automatically every day at noon.