Site connections & authorization
The connection model, each service's scope and read/write access, bind/unbind semantics, and troubleshooting when a connection fails.
The connection model#
Connections have two layers:
- Account-level authorization: a set of permissions you grant on the Google (or Microsoft / Cloudflare) side. Stored server-side and reusable across sites.
- Site-level binding: each site binds its own resources — a GA4 property, a GSC property, a GTM container, an AdSense account, a Bing site.
Note: Deleting a site cascades and revokes that site's authorization records; to disconnect one source only, disconnect it in Settings instead of deleting the site.
Scopes per service#
| Service | Scope | Access | Notes |
|---|---|---|---|
| GA4 | analytics.readonly | Read | Reads properties, data streams and reports |
| GSC | webmasters | Read + write | The URL Inspection API requires write scope; metricsKit only reads data and runs index inspections — it never modifies your site |
| AdSense | adsense.readonly | Read | Reads account and revenue reports |
| GTM | tagmanager.readonly | Read | Reads the container for checks and per-item verification; creating/publishing entities is done by you in GTM |
| PageSpeed Insights | No authorization | — | Public API, called by our servers on a schedule |
| Bing Webmaster | Microsoft OAuth (webmaster.readonly) | Read | Optional enhancement layer; disconnecting never affects Google data |
| Cloudflare | API Token (Settings/Zone/Analytics read-only) | Read | Edge traffic and bot data; the site must be on Cloudflare |
Tip: The authorization page labels each service with "used for / permission / privacy"; you can review status and re-authorize any time on the Google API page.
How to connect#
- Tick the services in the connect wizard → start authorization (a popup, no full-page redirect)
- Approve the requested scopes on the Google consent screen
- After the callback we discover your resources and match them by domain
- Unique match → binds automatically; several candidates → pick one in Settings; no match → create/verify the resource upstream first
Note: AdSense is account-level: one AdSense account spans all domains, so exactly one account is selected automatically and multiple accounts require a manual pick.
Binding and disconnecting#
- Change binding: pick another resource in Settings — no re-authorization needed.
- Disconnect a service: only that service's grant is revoked; Bing / Cloudflare are fully independent and never affect other sources.
- Shared grants: if a service's grant comes from a shared consent (e.g. an earlier authorization path), disconnecting only inserts a "revoked" placeholder and never revokes the shared grant.
- Re-authorize: after a scope upgrade (e.g. write access for GSC URL Inspection) or an expired token, use "Re-authorize".
Troubleshooting#
- Reports still empty after authorizing: usually an unbound resource (pick one in Settings) or upstream latency (see "Data latency & metric definitions").
- "Insufficient permission": the bound resource is not under that Google account, or the GSC property type is wrong.
- URL Inspection reports missing permission: users of the old read-only grant must re-authorize to gain write scope.
- Multiple sites: one Google account can serve several sites, but each site binds its own resources; switch sites with the picker in the header.
- Invalid token (invalid_grant): re-authorize on the Google API page.
Related docs#
- Quick start: /quickstart
- Per-source details: /gsc, /ga4, /gtm, /adsense, /bing, /pagespeed
- Data latency & metric definitions: /data-latency