Service account access to GA4 and Search Console

Why does the service account need no IAM roles?

This is the single most common point of confusion in wiring these APIs. IAM roles govern Google Cloud resources — buckets, VMs, BigQuery datasets. GA4 properties and Search Console properties are not Cloud resources; each has its own access list, and the APIs check that list. So the service account is created role-less, and a service account email gets added to each product the way you'd add a human teammate. Granting Editor on the project — the reflex fix — changes nothing about a 403 from either API.

How do you set it up, step by step?

1. In the Cloud console, create (or pick) a project. Its only job is to hold the API enablement and the service account.
2. APIs & Services → Library: enable the Google Analytics Data API and the Google Search Console API.
3. IAM & Admin → Service Accounts → Create. Name it, and when the wizard offers roles, skip that step.
4. On the new account: Keys → Add key → JSON. This downloads the only copy of the private key — handle it like a password (next section).
5. In GA4: Admin → Property access management → +, paste the service account email, role Viewer. Google documents the screen in Add, edit, and delete users. Grant on the property, not the account, unless you mean every property.
6. In Search Console: Settings → Users and permissions → Add user, same email, permission Restricted — read access is all an API reader needs. Reference: Managing owners, users, and permissions.

Scopes at request time stay read-only to match: …/auth/analytics.readonly and …/auth/webmasters.readonly.

How do you store the private key without corrupting it?

The JSON key contains a multi-line PEM, and multi-line values do not survive env-var round trips intact. Paste it raw into a deploy dashboard and the newlines arrive as literal \n; the first signature attempt then fails with the famously unhelpful error:1E08010C:DECODER routines::unsupported. Two working conventions, used in two systems behind this post:

• Store it escaped and un-escape on read: key.replace(/\\n/g, "\n"). Fine, but the failure when someone pastes it differently is still the decoder error.
• Base64 the whole PEM and decode on read — with a guard that turns the cryptic failure into an instruction:

# Extract just the PEM and base64 it — then delete the key file.
cat sa.json | jq -r .private_key | base64
rm sa.json

# In code: decode, then fail loudly if it isn't a PEM
const key = Buffer.from(process.env.GOOGLE_SA_PRIVATE_KEY_B64, "base64")
  .toString("utf8")
if (!key.includes("BEGIN") || !key.includes("PRIVATE KEY")) {
  throw new Error("GOOGLE_SA_PRIVATE_KEY_B64 did not decode to a PEM key")
}

Either way: the downloaded sa.json gets deleted once its two values are in the env file, and the gitignore gets a backstop entry for it — a key file that never exists in the repo can't be committed to it.

How do you verify access before writing any real code?

Between "key works" and "reports flow" sit four distinct failures — API not enabled, no grant, wrong property id, bad key — and they all surface as terse HTTP errors. Both systems behind this post ship a check command that mints a token, probes each API, and translates the response into the fix:

if (/SERVICE_DISABLED|has not been used in project/i.test(body)) {
  const api = body.match(/([a-z]+\.googleapis\.com)/)?.[1] ?? "the API"
  return `not enabled — turn on ${api} in APIs & Services → Library`
}
if (status === 403) return "permission denied — the robot has no grant yet"
if (status === 401) return "credential rejected — check the key in .env.local"

1. Mint a token (any Google auth library, or the raw JWT-bearer flow against oauth2.googleapis.com/token).
2. List what the robot can see: accountSummaries on the Analytics Admin API, and the sites list on the Search Console API. An empty list means the grant is missing — a much better answer than a bare 403.
3. Only then run a real report query. Configure property ids from what the probe printed, never from memory.

With access verified, the actual queries are the easy part: pulling GA4 reports and querying Search Console.

Questions