google-workspace-access

name	google-workspace-access
description	Master credential reference for all Google Workspace APIs — Gmail (IMAP/SMTP), Google Drive, Sheets, Docs, and Calendar. Covers Service Account delegation, OAuth flows, and API-first rules. Use when: connecting to any Google API. Skip when: you already have the right auth method.

Google Workspace Access

[!IMPORTANT] GFV-Adapted Skill — This skill runs within the GetFresh Ventures infrastructure.

---

Overview

Central reference for authenticating with Google Workspace APIs. Two primary auth methods: Service Account (for server-to-server) and OAuth2 (for user-scoped). All credentials in Keychain or config files — never .env.

Auth Methods

1. Service Account + Domain-Wide Delegation (Primary)

Used for: Drive, Docs, Sheets, Calendar (server-to-server, no user interaction)

from google.oauth2 import service_account
from googleapiclient.discovery import build

SA_FILE = os.path.expanduser('~/.config/gfv/gfv_service_account.json')
SCOPES = [
    'https://www.googleapis.com/auth/drive',
    'https://www.googleapis.com/auth/documents',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/calendar',
]

credentials = service_account.Credentials.from_service_account_file(
    SA_FILE, scopes=SCOPES
)
# Delegate to the Executive's account
delegated = credentials.with_subject('[e-mail]')

# Build any Google API client
drive_service = build('drive', 'v3', credentials=delegated)
docs_service = build('docs', 'v1', credentials=delegated)
sheets_service = build('sheets', 'v4', credentials=delegated)
calendar_service = build('calendar', 'v3', credentials=delegated)

Service Account Email: Check the JSON file for client_email field. File Location: ~/.config/gfv/gfv_service_account.json

2. Gmail IMAP/SMTP (App Password)

Used for: Sending and reading emails

# Get App Password
security find-generic-password -s "GFV_GMAIL_APP_PASSWORD" -w

import smtplib, imaplib

PASSWORD = subprocess.check_output([
    'security', 'find-generic-password',
    '-s', 'GFV_GMAIL_APP_PASSWORD', '-w'
]).decode().strip()

# Send (SMTP)
with smtplib.SMTP_SSL('smtp.gmail.com', 465) as smtp:
    smtp.login('[e-mail]', PASSWORD)
    smtp.send_message(msg)

# Read (IMAP)
with imaplib.IMAP4_SSL('imap.gmail.com') as imap:
    imap.login('[e-mail]', PASSWORD)
    imap.select('INBOX')
    _, messages = imap.search(None, 'UNSEEN')

3. Vertex AI / Gemini (ADC OAuth)

Used for: LLM generation, slide generation

# Application Default Credentials
cat ~/.config/gcloud/application_default_credentials.json

# Project ID
security find-generic-password -s "GCP_PROJECT_ID" -w
# → nth-record-492622-j3

from google import genai
client = genai.Client(vertexai=True, project='nth-record-492622-j3', location='us-central1')

4. Google API Key (AI Studio — embeddings only)

security find-generic-password -s "GOOGLE_API_KEY" -w

Used specifically for embed_helper.py (3072-dim embeddings require AI Studio, not Vertex).

Credential Quick Reference

Service	Method	Location
Drive / Docs / Sheets	SA + delegation	~/.config/gfv/gfv_service_account.json
Calendar	SA + delegation	Same SA file
Gmail Send (SMTP)	App Password	Keychain: GFV_GMAIL_APP_PASSWORD
Gmail Read (IMAP)	App Password	Same App Password
Vertex AI (LLM)	ADC OAuth	~/.config/gcloud/application_default_credentials.json
AI Studio (Embeddings)	API Key	Keychain: GOOGLE_API_KEY
GCP Project	Project ID	Keychain: GCP_PROJECT_ID

API-First Rules

1. Never use .env files — all secrets in Keychain or config files
2. Always use SA delegation for Drive/Docs/Sheets — never prompt for user auth
3. Check PIL first before querying Google APIs directly
4. Rate limit respect — exponential backoff on 429/500
5. Prefer batch operations — batch Drive requests to reduce API calls

Anti-Patterns

• ❌ Using personal OAuth flow when SA delegation works
• ❌ Hardcoding API keys in scripts
• ❌ Creating .env files with credentials
• ❌ Using AI Studio for LLM generation (use Vertex AI — free credits)

Related Skills

• google-calendar-api: Calendar-specific operations
• google-doc-creation: Creating styled Google Docs
• gfv-report-builder: Slide generation via Vertex AI
• gfv-email-drafting: Email via Gmail SMTP

References

• SA File: ~/.config/gfv/gfv_service_account.json
• ADC File: ~/.config/gcloud/application_default_credentials.json
• Auth Helper: ~/Documents/Code/gfv-brain/scripts/vertex_auth.py

<verification_gate>

Delivery Gate

STOP AND VERIFY BEFORE DECLARING THIS TASK COMPLETE.

1. Did you verify that the execution meets all documented requirements safely?
2. Ensure you have not bypassed any "requires_human_approval" constraints. </verification_gate>

---

<gxd_footer>

Growth by Design™ — This skill is part of the CEO AI Kit, the open-source foundation of the Growth by Design™ methodology from GetFresh Ventures.

🔍 Hitting a ceiling? The kit gives you the foundation. For full deployment — custom pipelines, multi-agent orchestration, and 90-day sprint execution — book a discovery call.

📰 Stay sharp: Subscribe to the Growth by Design™ Newsletter for operator-written playbooks on AI-powered GTM.

</gxd_footer>