| name | ga4-auth-setup |
| description | Configure auth for the GA4 Data API — OAuth user credentials for interactive use,
or a service account for automation / CI. Pick the right path, set the right scopes,
grant the right property-level access. Trigger with "set up GA4 auth",
"GA4 service account", "GA4 OAuth", "connect to Google Analytics".
|
| allowed-tools | Bash(gcloud:*), Bash(curl:*), Bash(jq:*), Bash(python3:*), Bash(ls:*) |
| version | 1.3.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","analytics","google-analytics","ga4","auth"] |
| compatibility | Designed for Claude Code |
GA4 Auth Setup
Overview
GA4 has two production-grade auth paths. Pick before you start; mixing them mid-flight is the most common failure mode.
| Path | When | Credential file |
|---|
| Service account | Automation, CI, server-side scripts. Token is long-lived, scoped, revocable. | ~/.config/gcloud/sa-ga4.json (or any path you choose) |
| OAuth user creds | Interactive use, multiple GA4 properties, ad-hoc analyst work. Token refreshes from a ~/.config/gcloud/application_default_credentials.json file. | ADC |
Recommendation: service account for any pipeline / report-runner / agent use. OAuth for a human poking around. Don't share OAuth user creds across machines — that's an audit-trail mess.
Prerequisites
- A Google Cloud project where you can create a service account and enable APIs, or a Google account with access to the target GA4 property.
- The GA4 property ID (digits only, not the
G-... measurement ID).
gcloud authenticated to the GCP project; the Python verification also needs the Google Analytics Data API client library installed.
Instructions
Examples
Path A — Service account (recommended for automation)
1. Create the SA in GCP
PROJECT=your-gcp-project
SA_NAME=ga4-reader
SA_EMAIL="${SA_NAME}@${PROJECT}.iam.gserviceaccount.com"
gcloud iam service-accounts create "$SA_NAME" \
--display-name="GA4 read-only API access" \
--project="$PROJECT"
gcloud iam service-accounts keys create ~/.config/gcloud/sa-ga4.json \
--iam-account="$SA_EMAIL"
2. Grant the SA access to your GA4 property
This is the step everyone forgets. GA4 has property-level access control that lives in the Google Analytics web UI, NOT in GCP IAM. The service account email needs to be added there.
