| 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.2.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","analytics","google-analytics","ga4","auth"] |
| compatibility | Designed for Claude Code |
GA4 Auth Setup
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.
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.
- Open https://analytics.google.com/
- Admin (bottom-left gear) → Property column → Property Access Management
- Add user: paste
$SA_EMAIL (e.g. ga4-reader@your-project.iam.gserviceaccount.com)
- Role: Viewer (read-only — anything more is over-privilege)
- Save
3. Enable the Data API in the SA's project
