Admin and Data API Reference

This appendix is a working reference for the Google Analytics Admin API, the Data API, and the Measurement Protocol calls that the audit and reconstruction of GA4 property 534525683 used. Every call here was run against the live property in Google Cloud project gen-lang-client-0444184725. The narrative that explains why each call mattered lives in Chapter 4, Auditing Methodology (Programmatic and Adversarial), and Chapter 6, The Server-Side Measurement Protocol; this appendix supplies the mechanics so a practitioner can copy, adapt, and run them. The service account is written id-01-{company}@gen-lang-client-0444184725.iam.gserviceaccount.com throughout.

D.1 Authentication: minting an impersonated token

The audit never downloaded a service-account key file. Instead the operator's own Google identity, granted the Service Account Token Creator role on the target service account, mints a short-lived OAuth access token by impersonation. A key file that never exists cannot leak.

# Mint a scoped, short-lived token by impersonating the service account.
TOKEN=$(gcloud auth print-access-token \
  --impersonate-service-account="id-01-{company}@gen-lang-client-0444184725.iam.gserviceaccount.com" \
  --scopes="https://www.googleapis.com/auth/analytics.edit")

# Use it as a Bearer token on any Admin or Data API request.
curl -s -H "Authorization: Bearer ${TOKEN}" \
  "https://analyticsadmin.googleapis.com/v1beta/properties/534525683"

The --scopes flag is load-bearing. Google's OAuth model grants a token exactly the scopes you name and nothing else, and several GA4 endpoints reject a token that lacks the precise scope even when the underlying GA4 role would allow the action. Mint a new token per scope family rather than requesting a broad scope you do not need.

A single token can carry several scopes if you pass a comma-separated list, but the audit deliberately kept the write scope out of read-only sessions so a mistaken PATCH could not fire from a session provisioned for inspection.

D.2 Admin API reference

Base host: analyticsadmin.googleapis.com. Most resources are stable on v1beta; Enhanced Measurement settings are only exposed on v1alpha, noted per row. The property is 534525683; the web data stream is 14548640408. All paths below are appended to https://<host>/<version>/.

Representative bodies

Create a custom dimension (analytics.edit):

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  "https://analyticsadmin.googleapis.com/v1beta/properties/534525683/customDimensions" \
  -d '{
    "parameterName": "service_type",
    "displayName": "Service Type",
    "scope": "EVENT"
  }'

error_message was registered the same way. It is safe to register because the application only ever sends bounded codes such as server_error and network_error, never raw user input; a dimension that could ingest free text would be a PII hazard, discussed in Chapter 10, Privacy and Consent by Design.

Create a key event (analytics.edit):

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  "https://analyticsadmin.googleapis.com/v1beta/properties/534525683/keyEvents" \
  -d '{ "eventName": "generate_lead", "countingMethod": "ONCE_PER_EVENT" }'

Raise event data retention (analytics.edit):

curl -s -X PATCH -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  "https://analyticsadmin.googleapis.com/v1beta/properties/534525683/dataRetentionSettings?updateMask=eventDataRetention" \
  -d '{ "eventDataRetention": "FOURTEEN_MONTHS" }'

The updateMask query parameter is mandatory on every PATCH. GA4 updates only the fields you name in the mask and leaves the rest untouched, so an omitted mask returns an error rather than silently overwriting the whole resource. Standard aggregate reports retain data effectively indefinitely regardless of this setting, so raising the cap from TWO_MONTHS to FOURTEEN_MONTHS changes only Explorations and funnels that lean on event- or user-scoped custom dimensions, which is precisely the by-service and by-county seasonal analysis this business needs.

Toggle Enhanced Measurement (analytics.edit, v1alpha):

curl -s -X PATCH -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  "https://analyticsadmin.googleapis.com/v1alpha/properties/534525683/dataStreams/14548640408/enhancedMeasurementSettings?updateMask=pageChangesEnabled,formInteractionsEnabled" \
  -d '{ "pageChangesEnabled": false, "formInteractionsEnabled": false }'

pageChangesEnabled double-fired page_view on client-side navigation, and formInteractionsEnabled auto-fired GA4's own form_start and form_submit, which collided with the site's custom form events. Chapter 8, Event Taxonomy and Custom Dimensions, records the collision and the fix.

D.3 Data API reference

Base host: analyticsdata.googleapis.com, version v1beta. Read scope: analytics.readonly. Two methods drove the audit's traffic and event queries.

Example runReport body, sessions by source and medium over the trailing 30 days:

curl -s -X POST -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  "https://analyticsdata.googleapis.com/v1beta/properties/534525683:runReport" \
  -d '{
    "dateRanges": [{ "startDate": "30daysAgo", "endDate": "today" }],
    "dimensions": [
      { "name": "sessionSource" },
      { "name": "sessionMedium" }
    ],
    "metrics": [
      { "name": "sessions" },
      { "name": "activeUsers" },
      { "name": "eventCount" }
    ],
    "orderBys": [{ "metric": { "metricName": "sessions" }, "desc": true }]
  }'

That query returned (direct)/(none) 234, google/organic 192, google/cpc 46, yahoo/organic 16, bing/organic 12, and the long tail down to one yelp.com/referral session. The paid row with no Ads link is what motivated the offline-revenue loop in Chapter 11, The Offline-Revenue Loop.

D.4 Measurement Protocol reference

The Measurement Protocol is not on the Admin host. Server-side events POST to the collection endpoint; a parallel debug endpoint validates a payload without recording it. Authentication is not an OAuth token but two query parameters: measurement_id (G-WH410Z73V1) and an api_secret created in the stream's data-stream settings.

The single most consequential defect in the entire audit lived in this one host string. The production code posted to https://www.google.com/mp/collect, which returns HTTP 404, so the server generate_lead never reached GA4 across the property's lifetime. The documented host https://www.google-analytics.com/mp/collect returns HTTP 204. Both were verified live with curl and the same payload. Chapter 6 dissects the failure; the lesson for this reference is blunt: the host is www.google-analytics.com, and a 204 with no body is success, not silence.

Validate before you trust:

curl -s -X POST \
  "https://www.google-analytics.com/debug/mp/collect?measurement_id=G-WH410Z73V1&api_secret=${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "1234567890.1680000000",
    "events": [{
      "name": "generate_lead",
      "params": {
        "currency": "USD",
        "value": 400,
        "form_source": "contact",
        "service_type": "termite",
        "session_id": "1680000000",
        "engagement_time_msec": 1
      }
    }]
  }'

The corrected payload validated with validationMessages: []. Swap debug/mp/collect for mp/collect to record. The production send included ip_override set to the request IP so the conversion geolocates to the user rather than the datacenter, sent only when a real ga_client_id was present, and carried session_id parsed from the _ga_<container> cookie so the event attributes to the originating session rather than (direct)/(none). The parameter parsing for both the legacy GS1 dot-delimited and newer GS2 dollar-delimited cookie formats is documented in Chapter 6 and reproduced in Appendix B.