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.
Related
- 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