setup oauth

📊 search-analytics
← Back to search-analytics 📄 Raw Markdown

Google Search Console OAuth 2.0 & API Setup Guide #

This guide walks through configuring Google Cloud OAuth 2.0 credentials to authorize your client application and ingest real Search Console analytics into SQLite.

1. Prerequisites #

  1. Google Account: An account with verified ownership or read permissions on at least one property in Google Search Console ↗.
  2. Google Cloud Project: A project in Google Cloud Console ↗.

2. Step-by-Step GCP Configuration #

Step 1: Enable the Google Search Console API #

  1. Open the Google Cloud Console API Library ↗.
  2. Search for Google Search Console API (formerly Webmasters API).
  3. Click Enable.
  1. Go to APIs & Services > OAuth consent screen.
  2. Select User Type:
    • External (standard for personal Gmail or Google Workspace accounts).
    • Internal (if restricted to your Google Workspace organization).
  3. Fill in basic app info:
    • App name: Search Analytics Local App
    • User support email: Your email address
    • Developer contact: Your email address
  4. Click Save and Continue.
  5. On the Scopes page, click Add or Remove Scopes and add:
    • https://www.googleapis.com/auth/webmasters.readonly (Read-only access to sites, sitemaps, and search analytics)
    • https://www.googleapis.com/auth/webmasters (Full management access)
  6. On the Test users page, click + Add Users and enter your Google account email address.
  7. Save and finish.

Step 3: Create OAuth 2.0 Client ID Credentials #

  1. Go to APIs & Services > Credentials.
  2. Click + Create Credentials > OAuth client ID.
  3. Select Application type: Web application.
  4. Set Name: Search Analytics Local App.
  5. Under Authorized redirect URIs, add both:
    • http://localhost:8080/oauth2callback
    • http://127.0.0.1:8080/oauth2callback
  6. Click Create.
  7. Download the client secret JSON file.

Step 4: Save Client Secret #

Copy the downloaded file to your local configuration folder:

bash 
mkdir -p ~/.config/gsc
cp ~/Downloads/client_secret_*.json ~/.config/gsc/client_secret.json

3. Authorization Flow & Token Management #

Once the client secret is placed at ~/.config/gsc/client_secret.json, start the companion server:

bash 
python3 scripts/search_analytics.py auth --port 8080
  1. Open http://localhost:8080 in your browser.
  2. Click Authorize with Google.
  3. Select your Google account and grant the requested permissions.
  4. Google redirects to /oauth2callback, exchanges the authorization code for an access token and refresh token, and automatically persists them to:

~/.config/gsc/credentials.json

The CLI utility will automatically refresh the access token using the stored refresh token on all subsequent runs.