All documentation

Account

Integrations

Connecting a Google account and mapping a property are two separate steps with two separate scopes, and why that distinction matters.

Connecting and mapping are different things

The Google page under Your profile, reached from Connected accounts there, is where you connect a Google account and then choose which Search Console and Analytics properties feed which of your projects. It sits under Your profile, not under any project or company, because the connection belongs to you. Those are two separate steps with two separate scopes, and the difference between them is the common reason a freshly connected account still leaves a project's Search or Site traffic screen empty: connecting maps nothing, so a project has no data until one of its properties is mapped.

Connecting stores one Google account's refresh token against your own user id, not against any project or company: the lookup behind every use of that connection finds it by matching your user id alone, with no project in the query at all, so the connection you make once covers every project you can map into, in every company, current and future (api/services/integrations/google/oauth.py#get_active_integration, #upsert_integration). Starting the OAuth handshake, for either product, checks nothing but who you are signed in as (api/routers/integrations.py#oauth_start, #ga4_oauth_start).

Mapping is the separate step underneath it, and it is scoped to one project at a time. A Search Console property or an Analytics property Google hands back after you connect is tied to a project by setting that property's own project field to that project's id, one property row, one project assignment (api/routers/integrations.py#map_property_to_project, #map_ga4_property_to_project).

Nothing is mapped for you. Completing the handshake stores the connection and attaches no property to any project, because a mapping decides whose Google data a project's members see, and that is a person's call (api/routers/integrations.py#oauth_complete). Reconnecting an account whose properties are already mapped does start those projects' imports there and then, for whichever of the two products the new connection covers, rather than leaving them for the next nightly run (api/routers/integrations.py#_projects_fed_by, #_enqueue_import).

What the screen offers instead is a suggestion. Listing your properties reconciles them with Google and, for each property not yet attached to a project, names the project it certainly belongs to, if there is one, with a "Map to" button beside the dropdown (api/routers/integrations.py#list_properties, #list_ga4_properties). A property's site has to be exactly equal to the domain of exactly one project you can write to: every active project of a company you are a member of, plus any active project where you are an editor (api/services/integrations/google/property_suggestions.py#load_writable_projects). Both sides are first lowercased and stripped of any scheme, port, path and leading www., so a subdomain is a different site, and two matching projects is an ambiguity it declines rather than guesses at (api/services/integrations/google/property_suggestions.py#match_project). Where the site comes from differs by product. Search Console reads the property's own URL. When you have a Domain property and URL-prefix properties for the same site, only the Domain property is suggested, since it covers every subdomain and protocol; two URL-prefix properties with no Domain property get no suggestion; and a project that already has a Search Console property, through anyone's connection, a teammate's included, gets none either (api/services/integrations/google/property_suggestions.py#suggest_gsc_projects). An Analytics property carries no URL, so the first time an unmapped one is listed, the hosts of its web data streams are read and kept, and the screen shows them under the property; when they cannot be read, the next listing tries again (api/services/integrations/google/property_sync.py#_record_web_hosts). It is suggested only when it is the only one of your unmapped properties tracking that project's site, and not when the project already gets the same Google property through a teammate's connection (api/services/integrations/google/property_suggestions.py#suggest_ga4_projects).

Taking a suggestion and picking a project from the dropdown are the same mapping, and nothing is mapped until you do one or the other. Either way requires write access to the project you are mapping into: both map handlers run the same access and role check every project-scoped write in the product uses, so a company member or an editor can map a property to a project and a viewer cannot (api/routers/integrations.py#map_property_to_project, #map_ga4_property_to_project). The screen reflects that check rather than letting the request go and fail: the project dropdown for each property lists every project you can open, but a project you can only read is shown marked "(view only)" and cannot be selected (frontend/src/routes/(app)/profile/google/+page.svelte#canMapTo). Unmapping asks the same question. Both unmap handlers first check that the property belongs to your own Google connection, and then, when that property currently has a project attached, run the same pair of checks the map handlers do against that project (api/routers/integrations.py#unmap_property, #unmap_ga4_property, api/dependencies.py#get_project_for_user, api/dependencies.py#require_write_access). Moving a property that already feeds one project into another detaches it too, so a move runs that same pair of checks against the project it leaves as well as the one it joins (api/routers/integrations.py#_require_detach_access). So a viewer cannot detach a property, by unmapping or by moving it, and neither can someone who has since been taken off the project they mapped it into, and on screen the Unmap button for a mapped property is disabled under that same canMapTo check, read against the project the property is currently attached to (frontend/src/routes/(app)/profile/google/+page.svelte#canMapTo). A property attached to no project reaches neither check, because there is no project to check against, and detaching it changes nothing in any case.

This is why a connection of your own and a project with no data are not a contradiction: the account can be genuinely connected while this particular project simply has no property mapped to it yet. The reverse holds too. Once made, a mapping belongs to the project, so every member's Search, Search plan, Site traffic and AI Traffic screens read it whether or not they have connected Google themselves; only a mapping whose connection was disconnected, or whose property Google no longer lists, stops counting (api/routers/integrations.py#project_google_status). See Troubleshooting for what each of those states looks like on screen, and what to do about it.

Search Console and Analytics behave differently, but not in every direction

Mapping does not work the same way for the two products, and the difference sits in only one of the two directions a mapping can be read.

From a project looking down at its properties: a project may hold at most one Search Console property, counted across every member's connection. Before completing a new mapping, the handler looks for the property already holding the target project, whoever's connection it came through (api/services/integrations/google/project_mapping.py#gsc_property_for_project). When that is one of your own properties, it clears that property's mapping first, an atomic swap that keeps a project pinned to one Search Console property no matter how many times you remap it (api/routers/integrations.py#map_property_to_project). When it came through another member's connection, the handler leaves their choice alone and refuses with a conflict naming the property, as long as that member can still unmap it themselves; it takes the mapping over only when they cannot, because their connection was disconnected, Google no longer lists the property, or they no longer have write access to the project (api/routers/integrations.py#_holder_can_unmap). The settings screen names the property feeding the selected project when it comes through someone else's connection, so the refusal is not a surprise (frontend/src/routes/(app)/profile/google/+page.server.js#sharedGscProperty). Analytics carries no one-per-project rule: a project can hold as many different Analytics properties as you choose to give it. What it cannot hold is the same Google Analytics property twice. Every member's connection keeps its own copy of each property it can see, and imported traffic is stored per copy, so a second copy on one project would count every session twice; the database allows one copy of a given property per project (api/models/ga4_property.py#Ga4Property). A teammate's copy is handled the way Search Console handles a teammate's property: mapping yours is refused while they can still unmap theirs, and otherwise takes it over (api/routers/integrations.py#map_ga4_property_to_project). Unmapping a copy leaves its imported traffic counted under the project, so whenever a copy is mapped, every earlier copy's history for that project, mapped or not, is handed to it a whole day at a time, and its first import re-fetches 180 days (api/services/integrations/google/project_mapping.py#attach_ga4_row, api/services/integrations/google/project_mapping.py#merge_ga4_history). Each import then replaces that window for every copy of the property, not only its own, so no day is counted twice (api/services/integrations/google/ga4_attribution.py#import_ga4_daily_for_project). The settings screen states this difference in its own copy, and the flag in the Search Console picker runs the other way round from what you might expect: what is marked is a project that one of your own properties already holds, so that choosing it tells you this mapping will move that one over. A project held through another member's connection carries no mark; choosing it is refused or takes the mapping over, as described above (frontend/src/routes/(app)/profile/google/+page.svelte#takenProjectIds).

From a property looking up at its project, the two products agree, and this is the direction worth checking before assuming the asymmetry runs both ways. Both the Search Console swap above and the Analytics mapping handler write a single project id onto the property being mapped, replacing whatever was there before rather than adding to a list (api/routers/integrations.py#map_property_to_project, #map_ga4_property_to_project), so a single property can be attached to only one project at a time in either system. Nothing about Analytics' looser rule above lets one Analytics property serve two projects at once; it only lets one project hold more than one property.

The scopes you are granting

Connecting asks Google for exactly two possible scopes, named as constants in the code you can check directly, and both are read-only. webmasters.readonly is the Search Console scope, and analytics.readonly is the Analytics one; neither string carries a write, edit, or manage permission, and nothing else in the OAuth flow ever requests a broader scope than these two (api/services/integrations/google/oauth.py#GSC_SCOPE, #GA4_SCOPE, #build_authorization_url). Which of the two you are asked to grant depends on which Connect button you use: the Search Console button requests only its own scope, while the Analytics button requests its own scope plus Search Console's too if you already granted that one, so one consent screen can cover both going forward (api/routers/integrations.py#oauth_start, #ga4_oauth_start). Every authorization request also sets Google's offline access and forces the consent screen again even for a returning user, specifically so a refresh token comes back on every connect rather than only the first time (api/services/integrations/google/oauth.py#build_authorization_url).

One control on this same screen reaches past the connection itself: naming the Analytics events that count as a conversion for a project. Changing that list requires the same write access mapping does (api/routers/integrations.py#update_conversion_events), and what naming an event actually changes about the numbers elsewhere in the product is AI traffic's to explain, not this page's.

Disconnecting, and reconnecting later

Disconnect Google asks first. Its dialog says that Search Console and Analytics imports stop for every project your properties feed, and that your mappings and the data already imported are kept; Stay connected cancels, and a refusal is shown inside the dialog (frontend/src/routes/(app)/profile/google/+page.server.js#actions).

Disconnecting asks Google to revoke the stored refresh token, a best-effort call that is swallowed if it fails, and then marks the connection revoked by stamping a timestamp on it. It does not delete the row that holds the connection: the code sets revoked_at and commits, nothing more (api/routers/integrations.py#disconnect, api/services/integrations/google/oauth.py#revoke_refresh_token). Every property mapping you had is left exactly as it was: disconnecting never touches a property's project_id, and nothing keyed off revoked_at deletes a previously imported day of Search Console or Analytics data either. What actually stops is new data: the function every import route calls to get a working access token checks for a live, unrevoked connection first and returns nothing once one has been disconnected (api/services/integrations/google/oauth.py#get_active_integration, #get_access_token_for_user).

Reconnecting later reuses that same row rather than creating a new one: the upsert that runs at the end of a successful OAuth handshake finds the existing connection by your user id, overwrites its token and scopes, and clears revoked_at (api/services/integrations/google/oauth.py#upsert_integration). Because disconnecting never touched your mappings, every property you had mapped before is still mapped the moment the reconnected token starts working again, with nothing to redo.

When the screen cannot read something

Each read on this screen fails on its own, and a failure is never shown as an empty answer (frontend/src/lib/server/google-status.js#loadGoogleConnection). When your connection status cannot be checked, the Google account card reads "Connection status unknown" with Retry, and offers neither Connect nor Disconnect, since an account that may already be connected should not be asked to connect again. When Google does not return your Search Console or Analytics properties, that list says so with Retry instead of "No verified properties on this Google account". When your project list cannot be loaded, the screen says properties cannot be mapped or unmapped right now. And when the selected project's conversion events cannot be read, the event editor is held back with Retry, because saving from an empty editor would replace the project's real events with nothing.

When the callback fails

Google redirects your browser back after you respond to the consent prompt, to a callback address that has not changed, /settings/integrations/google/callback, so the Google Cloud client needs no change; the callback then returns you to the Google page under Your profile (frontend/src/routes/(app)/settings/integrations/google/callback/+server.js#SETTINGS_PATH). That redirect is the only path a broken connection attempt takes, so it is worth knowing exactly what each failure on it does. If Google's own redirect carries an error, or is missing the code or state it should carry, the callback never calls the backend at all: it bounces straight back with a generic failure shown. Otherwise it hands the code and state to the backend, which can reject the attempt for one of three reasons: the state token does not match what was issued for you or has expired, Google refused to exchange the code, or Google did not return a refresh token at all, which happens when you had already granted access before and this attempt did not force a fresh consent screen (api/routers/integrations.py#oauth_complete). The frontend recognizes all three of those reasons by name (frontend/src/routes/(app)/settings/integrations/google/callback/+server.js#known), but only two get their own message: a rejected code and a missing refresh token each explain what happened and what to do next, while an expired state token and anything unrecognized both collapse into the same generic "try again" message. A successful callback carries no such detail: it redirects with a plain success flag that shows a one-time confirmation.

Not gated by plan

Neither connecting nor mapping checks your plan at any point. Besides the project list it shares with the rest of the app, this screen calls thirteen Google handlers: reading the connection's status, reading which properties feed the selected project, starting the handshake for either product, disconnecting, listing discovered Search Console properties, listing discovered Analytics properties, mapping and unmapping one of each, and reading and writing the conversion-event list. A fourteenth, completing the handshake, is reached from Google's redirect rather than from the screen itself. Every one of them reads your identity; mapping a property, unmapping one that currently has a project, and saving a conversion-event list additionally read your role on that project, and reading the conversion-event list or which properties feed the project requires membership on it. None of the fourteen reads a plan or a subscription at all (api/routers/integrations.py#integration_status, #project_google_status, #oauth_start, #ga4_oauth_start, #oauth_complete, #disconnect, #list_properties, #list_ga4_properties, #map_property_to_project, #unmap_property, #map_ga4_property_to_project, #unmap_ga4_property, #get_conversion_events, #update_conversion_events). That puts this screen outside every gate described on Plans and limits: what you can connect and map here is the same regardless of which company's plan governs the project you are mapping into.

  • Search performance: what a mapped Search Console property actually feeds, once it has one
  • Traffic: what a mapped Analytics property feeds beyond the AI-referred slice
  • AI traffic: the AI-referral reading of the same Analytics connection, including how naming a conversion event changes it
  • Troubleshooting: the connected-but-unmapped and mapped-but-empty states this page's central distinction explains

Last verified 2026-10-29

Start monitoring your AI visibility.

See how AI search engines talk about your brand.

Free to start. No credit card required.