Google Workspace
Overview
Interact with Google Drive, Gmail, Calendar, and Docs using OAuth authentication. Supports file uploads, folder management, email search, calendar search, and document operations.
Quick Decision Tree
What do you need?
│
├── Google Drive
│ ├── Search files/folders → references/drive-search.md
│ │ └── Script: scripts/gdrive_search.py
│ │
│ ├── Upload files → references/drive-upload.md
│ │ └── Script: scripts/google_drive_upload.py
│ │
│ ├── Create folder structure → references/folder-structure.md
│ │ └── Script: scripts/gdrive_folder_structure.py
│ │
│ ├── Create client folder → references/create-folder.md
│ │ └── Script: scripts/create_client_folder.py
│ │
│ └── Search transcripts → references/transcript-search.md
│ └── Script: scripts/gdrive_transcript_search.py
│
├── Gmail
│ └── Search emails → references/gmail-search.md
│ └── Script: scripts/gmail_search.py
│
└── Calendar
└── Search meetings → references/calendar-search.md
└── Script: scripts/google_calendar_search.py
Environment Setup
OAuth credentials are stored locally after first authentication.
Required Files
client_secrets.json - From Google Cloud Consolesettings.yaml - PyDrive2 configurationmycreds.txt - Auto-generated OAuth tokens
First-Time Setup
- Go to Google Cloud Console
- Enable APIs: Drive, Gmail, Calendar, Docs
- Create OAuth 2.0 credentials (Desktop app)
- Download as
client_secrets.json
- Run any script - browser opens for OAuth consent
Common Usage
Search Client Folder
python scripts/gdrive_search.py folder "Microsoft"
Upload Files
python scripts/google_drive_upload.py --files *.png --folder "Clients/Acme/Assets"
Search Emails
python scripts/gmail_search.py --domain "microsoft.com" --days 14
Search Calendar
python scripts/google_calendar_search.py "Microsoft" --days-back 30
OAuth Scopes
| Scope |
Purpose |
drive |
Full Drive access |
spreadsheets |
Sheets access |
documents |
Docs access |
gmail.readonly |
Read emails |
calendar.readonly |
Read calendar |
Cost
Free - Google Workspace APIs have generous free quotas.
Security Notes
Credential Handling
client_secrets.json - OAuth app credentials (never commit to git)mycreds.txt - User OAuth tokens (never commit to git, add to .gitignore)settings.yaml - PyDrive2 config (can be committed, no secrets)- Tokens auto-refresh; revoke via Google Account settings if compromised
- Never share OAuth credentials between users/machines
Data Privacy
- Access to user's personal Google Drive, Gmail, and Calendar
- Files may contain confidential business information
- Email content is highly sensitive - minimize storage
- Calendar events may contain private meeting details
- Shared Drive access respects original permissions
Access Scopes
- Request minimum required scopes:
drive - Full Drive access (read/write)drive.readonly - Read-only Drive access (preferred when possible)spreadsheets - Google Sheets accessdocuments - Google Docs accessgmail.readonly - Read-only email accesscalendar.readonly - Read-only calendar access
- Review/revoke access: https://myaccount.google.com/permissions
Compliance Considerations
- OAuth Consent: Users explicitly consent to access scopes
- GDPR: Google Workspace data contains EU user PII
- Data Residency: Google Workspace may have data residency requirements
- Shared Drives: Respect organizational sharing policies
- Audit Trail: Google Admin Console tracks API access
- Credential Security: Store
client_secrets.json securely, not in repos
Troubleshooting
Common Issues
Issue: OAuth token expired
Symptoms: "Invalid credentials" or "Token has been expired or revoked" error
Cause: OAuth refresh token expired or revoked
Solution:
- Delete
mycreds.txt file
- Re-run any script to trigger fresh OAuth flow
- Complete the browser authorization
- New
mycreds.txt will be created automatically
Issue: File not found
Symptoms: "File not found" error with valid file ID
Cause: No access to file, file deleted, or wrong file ID
Solution:
- Verify file ID from the Google Drive URL
- Check file sharing permissions
- Ensure OAuth user has access to the file
- Try accessing file directly in browser first
Issue: Quota exceeded
Symptoms: "User rate limit exceeded" or "Quota exceeded" error
Cause: Too many API requests in 24-hour period
Solution:
- Wait 24 hours for quota reset
- Create a new Google Cloud project with fresh quota
- Implement exponential backoff in scripts
- Reduce frequency of API calls
Issue: settings.yaml missing
Symptoms: "settings.yaml not found" or PyDrive2 configuration error
Cause: Missing PyDrive2 configuration file
Solution:
- Copy from template:
cp settings.yaml.example settings.yaml
- Ensure
client_secrets.json path is correct in settings
- Verify save_credentials_backend is set to "file"
- Check settings.yaml is in the script's working directory
Issue: client_secrets.json invalid
Symptoms: "Invalid client secrets" or OAuth configuration error
Cause: Malformed or incorrect OAuth credentials file
Solution:
- Re-download from Google Cloud Console
- Ensure "Desktop app" type was selected when creating credentials
- Check JSON format is valid
- Verify redirect URIs are configured for local auth
Issue: Scope access denied
Symptoms: "Insufficient permission" error
Cause: OAuth consent missing required scopes
Solution:
- Delete
mycreds.txt to reset OAuth session
- Re-authenticate and accept all requested scopes
- Verify scopes in
settings.yaml match script requirements
- Check Google Cloud Console for scope restrictions
Resources
- references/drive-search.md - Search files and folders
- references/drive-upload.md - Upload files to Drive
- references/folder-structure.md - Create folder hierarchies
- references/create-folder.md - Create client folders
- references/transcript-search.md - Search transcript files
- references/gmail-search.md - Search Gmail
- references/calendar-search.md - Search calendar meetings
Integration Patterns
Drive to Video Production
Skills: google-workspace → video-production
Use case: Assemble course videos from Drive folder
Flow:
- Search Drive for video folder with lesson files
- Download videos via video-production scripts
- Stitch videos with title slides and upload final output
Templates to Content
Skills: google-workspace → content-generation
Use case: Generate documents from branded templates
Flow:
- Load template from Drive (proposal, report format)
- Generate content via content-generation
- Create new Google Doc with formatted content
Calendar to Transcripts
Skills: google-workspace → transcript-search
Use case: Find meeting recordings from calendar events
Flow:
- Search calendar for meetings with specific client
- Get meeting dates and titles
- Search transcript-search for matching recordings
