ga4-auth-setup

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.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
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          # the project that will own the SA
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"

# Generate a key (file lands locally)
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.

1. Open https://analytics.google.com/
2. Admin (bottom-left gear) → Property column → Property Access Management
3. Add user: paste $SA_EMAIL (e.g. [e-mail])
4. Role: Viewer (read-only — anything more is over-privilege)
5. Save

3. Enable the Data API in the SA's project