Connect
Connect a GA4 property to a profile with Google sign-in, from the dashboard or with the connect API.
Connect a GA4 property
Request the authorization link for a profile, then send the user to authUrl:
curl "https://zernio.com/api/v1/connect/googleanalytics?profileId=PROFILE_ID&redirect_url=https://example.com/done" \
-H "Authorization: Bearer $ZERNIO_API_KEY"{ "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=…", "state": "…" }The user signs in with Google and allows read access to Analytics. What happens next depends on how many GA4 properties their Google account can read:
- One property: Zernio connects it straight away.
- Several properties: the user picks one on a page hosted by Zernio.
Zernio then saves the account and redirects to redirect_url (or the dashboard) with connected=googleanalytics, profileId, accountId and username (the property name).
Show your own property picker
To keep users in your app when they can read several properties, add headless=true to redirect_url. Instead of Zernio's page, Zernio redirects to your redirect_url with step=select_property, profileId, platform=googleanalytics and a pendingDataToken.
List the properties with that token and show them in your own UI:
curl "https://zernio.com/api/v1/connect/googleanalytics/properties?pendingDataToken=TOKEN" \
-H "Authorization: Bearer $ZERNIO_API_KEY"{ "properties": [{ "propertyId": "312456789", "displayName": "acme.com", "accountId": "1", "accountName": "Acme Inc" }] }Then connect the one the user picks, and send the user to the returned redirect_url:
curl -X POST "https://zernio.com/api/v1/connect/googleanalytics/select-property" \
-H "Authorization: Bearer $ZERNIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "pendingDataToken": "TOKEN", "propertyId": "312456789" }'Both calls need your API key (or connect token) for the same profile, because the token passes through your own URLs and does not work on its own. It expires after one hour.
Listing does not consume the token, and a refused or failed select leaves it usable for a retry. A user with only one property never reaches this step: it connects straight away.
Connect more than one property
Each connected property is one account. To read another property, connect it to a different profile. List the connected properties with GET /v1/accounts?category=analytics.
How it behaves
- Zernio asks only for
https://www.googleapis.com/auth/analytics.readonly. It cannot change the property or its settings. - Access renews by itself. If Google refuses to renew it, for example after the user removes Zernio from their Google account, the account is marked disconnected.
- A failed connect redirects with
error,platform=googleanalyticsanderror_message.
If it fails
| Error | Cause | Fix |
|---|---|---|
googleanalytics_access_denied | The user declined on Google's consent screen | Start the connect again and allow access. |
googleanalytics_scope_missing | The user unticked the Analytics permission | Start the connect again and keep the permission ticked. |
googleanalytics_no_properties | The Google account cannot read any GA4 property | Give it access to a GA4 property in Google Analytics, then connect again. |
googleanalytics_no_refresh_token | Google did not return a long-lived token | Start the connect again. If it repeats, remove Zernio from the Google account's third-party access first. |
googleanalytics_invalid_state | The link expired or was already used | Request a fresh authUrl. |
googleanalytics_auth_failed | Google returned to Zernio without an authorization code | Start the connect again; contact support if it repeats. |
googleanalytics_connection_failed | Google refused the code exchange, or the property could not be read or saved | Start the connect again; contact support if it repeats. |
503 on GET /v1/connect/googleanalytics | Google Analytics is not configured on this Zernio environment | Contact support. |