TraceLinker
integrations· 10 min read

Google Search Console Integration - Verified Sites, URL Inspection, Read-Only OAuth

Connect TraceLinker to Google Search Console with read-only OAuth. Browse verified sites, inspect indexing status, and validate backlink source pages without leaving the dashboard.

Google Search Console Integration - Verified Sites, URL Inspection, Read-Only OAuth

TraceLinker integrates with Google Search Console using a read-only OAuth scope (webmasters.readonly). The integration is optional - you can run audits via CSV upload alone - but enabling GSC unlocks two helpful workflows for SEO professionals: confirming you are operating on the right verified property, and validating whether backlink source pages are actually indexed by Google.

This article covers what the integration does, what it deliberately does not do, the setup flow, security architecture, troubleshooting, and best practices for using GSC alongside TraceLinker.

What the integration does

1. List your verified sites

Once connected, your verified Search Console properties appear in /dashboard/settings. We display:

  • The site URL (https://yourdomain.com/ for URL-prefix properties or sc-domain:yourdomain.com for domain properties).
  • Your permission level on the property (siteOwner, siteFullUser, siteRestrictedUser).

This makes it easy to confirm you are looking at the correct property when starting a new audit. The site URL auto-fills the target_domain field on the New Audit form, eliminating typos and ensuring URL prefix vs. domain property consistency.

For agencies managing multiple client properties under the same Google account, all verified properties appear in the list. You can pick the right one per audit without switching Google accounts in the browser.

2. URL inspection (on-demand)

For any source page in your audit results, you can call Google's URL Inspection API to see:

  • Indexing verdict - PASS, NEUTRAL, or FAIL. PASS means the page is indexed and eligible to appear in search results.
  • Coverage state - human-readable reason if not fully indexed (e.g., "Crawled - currently not indexed", "Discovered - currently not indexed").
  • Last crawl time - when Googlebot last fetched the page.
  • Crawled-as user agent - mobile or desktop crawler used.

This helps you understand whether a backlink's source page is even indexed by Google. An unindexed source page passes essentially zero SEO value through the link, regardless of how high its hypothetical authority would be. URL inspection turns "is this link worth chasing?" into a single click.

For backlinks added to monitoring with GSC connected, the dashboard shows a small index status indicator next to each source URL. If the status is FAIL or NEUTRAL, the link gets a "low signal value" flag in the priority view - useful for triage decisions.

What the integration does NOT do

We are explicit about this because it is the most common confusion users bring from other tools.

It does not import your backlinks. Google's public Search Console API does not expose the backlinks shown in the GSC UI. We checked. Many tools claim "GSC backlink import" but actually rely on undocumented or scraped endpoints that break when Google updates the UI - we are not willing to ship a feature whose reliability we cannot guarantee.

For backlink lists, you have two reliable options:

  1. Manual export from GSC UI - Search Console -> Links -> Top linking sites -> Export -> CSV. Upload to TraceLinker's New Audit page. Takes about 60 seconds end-to-end.
  2. Export from a third-party tool (Ahrefs, Semrush, Moz, Majestic) and upload the CSV the same way.

We are transparent about this so you do not waste time waiting for a feature that cannot exist on the public API surface.

Setup steps

Prerequisites

  • A Google account with at least one verified Search Console property.
  • Owner or full-user permission on the properties you want to use (restricted-user permission also works but is limited).

Step-by-step

  1. Go to /dashboard/settings and scroll to the Google Search Console card.
  2. Click Connect Google Search Console. You will be redirected to Google's OAuth consent screen.
  3. Sign in to the Google account that owns your Search Console properties.
  4. Approve the read-only scope. The consent screen will explicitly list webmasters.readonly and explain that the application will be able to view (but not modify) your Search Console data.
  5. You will be redirected back to the Settings page with a green "Connected" badge and your verified property list rendered.

The connection stores an encrypted OAuth refresh token so we can refresh access tokens without asking you to re-authorize on each session. Refresh tokens are encrypted at rest using application-layer AES.

Disconnect any time

Click Disconnect in the same card. The refresh token is deleted immediately from our database. You can also revoke access from your Google Account permissions page - revoking there invalidates the token globally regardless of our database state.

After disconnecting, your audit data and monitoring stay intact. Only the GSC-specific features (verified site list, URL inspection) become unavailable until you reconnect.

Security architecture

For SEO leads in regulated industries who need to defend tool selection against IT/security review, here is what actually happens behind the OAuth flow.

Scope limitation

We only request webmasters.readonly. This scope grants:

  • Listing verified sites and their permission levels.
  • Reading URL inspection results.
  • Reading search analytics data (search performance, queries, pages).

It explicitly does NOT grant:

  • Modifying Search Console data.
  • Submitting URLs for indexing.
  • Modifying the disavow file in Search Console.
  • Verifying or unverifying properties.
  • Reading from any other Google service (Gmail, Drive, Calendar, etc.).

Even if our system were compromised, the worst-case for connected accounts is read access to Search Console - no write actions are possible with this scope.

Token storage

Refresh tokens are stored encrypted at rest in our Postgres database using AES-256-GCM with application-layer key management. Access tokens (short-lived, 1 hour TTL) are kept in memory and not persisted. The encryption key is environment-injected and never logged.

State parameter validation

The OAuth flow uses a signed state parameter (HMAC-SHA256 with a server-side secret) to prevent CSRF and replay attacks. The state encodes the user ID and a timestamp; we reject states older than 10 minutes or signed by a different secret.

Audit logging

OAuth connect, disconnect, token refresh failure, and URL inspection calls are logged with timestamp and user ID. Logs are retained for 90 days for security review and rotated automatically.

OAuth setup for self-hosters

If you are running TraceLinker on your own infrastructure, you need a Google Cloud project with Search Console API enabled and an OAuth client configured.

Required environment variables

GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...
GSC_STATE_SECRET=<generate with openssl rand -hex 32>

Required redirect URI

In your Google Cloud Console OAuth client config, whitelist:

https://your-deployment-domain.com/api/integrations/google/callback

For localhost development:

http://localhost:3000/api/integrations/google/callback

Required scope

Add https://www.googleapis.com/auth/webmasters.readonly to your OAuth consent screen's scope list.

For full self-hosting documentation, see the Security page.

Troubleshooting common issues

"No verified properties found" after connect

Symptom: You connected successfully but the property list is empty.

Causes and fixes:

  1. Wrong Google account - you signed in with an account that does not own any Search Console properties. Disconnect, then reconnect with the correct account.
  2. Property is unverified - verify the property in Search Console first (DNS TXT record or HTML file upload), then refresh our settings page.
  3. Sub-user without API permission - sub-users with restricted permission sometimes do not see all properties via API. Ask the owner to grant full-user access.

"Token expired" or "invalid_grant"

Symptom: Verified sites list goes blank, or URL inspection returns an authentication error.

Causes and fixes:

  1. You revoked access in Google Account settings - reconnect from /dashboard/settings.
  2. The refresh token was rotated by Google due to inactivity - reconnect.
  3. Your Google Cloud OAuth client was modified (self-host only) - regenerate the client secret and redeploy.

URL inspection returns "Quota exceeded"

Symptom: URL inspection works for the first few pages, then fails.

Cause: Google's URL Inspection API has a strict rate limit (currently ~600 calls per day per property). We throttle calls to stay under the limit, but heavy use can hit it.

Fix: Wait until the next day, or use URL inspection more selectively (only on backlinks you are actively considering for outreach).

Data appears stale or out of sync

Symptom: Search Console shows different metrics than our dashboard.

Cause: The Search Console API has a 24-48 hour delay relative to the Search Console UI for some metrics, especially URL inspection and search analytics. This is a Google-side limitation.

Fix: Use the Search Console UI directly for time-sensitive verification.

Best practices

1. Connect early, audit later

Connect GSC before you start monitoring. Index status is then available from the moment you add a backlink, not retroactively.

2. Use URL inspection selectively

URL inspection has a per-property quota. Reserve calls for high-priority backlinks where the index status materially affects your decision (whether to chase outreach for a lost link, whether to disavow a borderline source).

3. Cross-check disavow uploads

If you upload a disavow file generated by TraceLinker, the Search Console UI is the right place to verify the upload landed correctly and to monitor reconsideration request status.

4. Use verified site auto-fill

When starting a new audit, pick the target domain from the GSC dropdown rather than typing manually. This avoids URL-prefix vs domain-property mismatches that can cause confusing audit results.

5. Disconnect before changing Google accounts

If you switch to a different Google account, disconnect first then reconnect. Switching accounts mid-session can leave stale tokens that fail silently.

Privacy and data handling

  • We only request the read-only Webmasters scope.
  • We do not modify your Search Console data under any circumstance.
  • We do not share your GSC data with anyone, including aggregating it for model training or analytics.
  • Refresh tokens are encrypted at rest.
  • All API calls are made server-to-server (your Google credentials never reach the browser).
  • Tokens are deleted within minutes of disconnect.
  • See our Privacy Policy for full data handling, including retention windows for audit logs and your right to request data export or deletion.

Frequently asked questions

Does GSC integration cost extra? No. The integration is included on every plan, including the free plan.

Will connecting GSC affect my Search Console data? No. We only read. We never write, modify, or submit anything.

Can I connect multiple Google accounts? Currently one Google account per TraceLinker workspace. Multi-account support is on the roadmap for agencies managing properties across separate client Google accounts.

Why does Google's API not expose my full backlink list? Public API parity with the Search Console UI is incomplete and has been for years. Google has not communicated plans to expose backlinks via API. We do not know why and we have stopped speculating.

Can I use GSC integration without uploading a CSV? Not for audit-style workflows. The audit pipeline needs a backlink list to score, and that list comes from CSV upload. URL inspection on individual URLs works without uploading anything.

Can I export URL inspection results in bulk? Currently URL inspection is on-demand per URL. Bulk export is on the roadmap.

What if Google deprecates the Webmasters API in the future? We will adapt. The integration is built around a stable abstraction layer; any underlying API changes are isolated to one module. Your audit and monitoring data are independent of GSC and will continue to work even if the integration is paused.

Get started

Sign up free and connect your Search Console in under a minute. For deeper coverage of the rest of the workflow, see Lost backlink recovery and Disavow file generator.