Google Ads API Setup

Purpose: Get your Google Ads API connection working from scratch. This is the prerequisite for every other skill that queries or modifies Google Ads accounts.

Type: Setup / onboarding skill (one-time — run once per machine)

Time required: ~30 minutes

When to Invoke

Auto-invoke when user says:

• "Set up Google Ads API"
• "Generate credentials"
• "Create google-ads.yaml"
• "OAuth setup for Google Ads"
• "Test my API connection"
• "How do I get a refresh token"

Or when they hit common authentication errors:

• google.auth.exceptions.RefreshError: invalid_grant
• "My refresh token keeps expiring every 7 days"
• redirect_uri_mismatch
• Request had invalid authentication credentials
• The developer token is not approved
• login_customer_id is required

What This Skill Does

1. Walks the user through the 9-step Google Cloud Console + OAuth + Developer Token flow (see README.md), including the Internal-vs-External consent screen decision and publishing External apps to production so refresh tokens don't expire every 7 days
2. Generates their refresh token via generate_credentials.py — one consent covering Google Ads + Google Sheets + Drive read-only, because the Sheets-writing skills in this catalog (non-serving-keyword-scanner, ads-checker, rsa-refresh, sqr-pipeline, and others) reuse this same token from google-ads.yaml for their report output
3. Verifies connectivity via test_connection.py
4. Produces a working google-ads.yaml at their project root

Token generated before 2026-07-17? It carries only the Ads scope — Ads queries work, but Sheets-writing skills 403. Re-run generate_credentials.py once and paste the new refresh_token into your google-ads.yaml. Scopes are fixed when a token is minted; they can't be added afterward.

Files in This Skill

How to Run

Step 1 — Generate credentials (after README steps 1-6: OAuth client created, packages installed)

python generate_credentials.py --client-secrets client_secret.json

Opens a browser URL. User signs in → grants access → refresh token prints to terminal. The consent asks for Google Ads, Google Sheets, and Drive read-only together — if Google shows individual checkboxes, tick all three (the script warns if any were skipped).

Step 2 — Copy the example YAML

cp google-ads.example.yaml google-ads.yaml

Fill in client_id, client_secret, refresh_token, developer_token, login_customer_id.

Step 3 — Test the connection

python test_connection.py --config google-ads.yaml

Expected output: list of accounts under the MCC.

Common Failure Modes

See README.md for the full troubleshooting list.

Security Notes

• Never commit google-ads.yaml, client_secret.json, or the refresh token itself
• .gitignore in this repo already excludes *.yaml, *.env, and client_secret*.json
• Refresh tokens grant full access to linked Google Ads accounts — plus, with the scopes this generator requests, read/write access to your Google Sheets and read access to your Drive file listing. Treat as passwords
• Revoke compromised tokens at myaccount.google.com/permissions

Related Skills

• mutation-safety — install before any skill that modifies accounts
• gaql-query-patterns — start here once API is working
• google-ads-query — general-purpose GAQL executor

Installation

Clone the repo so you get the full folder — both scripts, the example yaml, and the diagrams the README embeds:

git clone https://github.com/fourteenwm/ppc-ai-skills.git
cp -r ppc-ai-skills/google-ads-api-setup .claude/skills/google-ads-api-setup