---
title: "Get Google Search Console OAuth connect URL"
method: GET
path: "/v1/connect/googlesearchconsole"
tags: ["Connect"]
---

# Get Google Search Console OAuth connect URL

`GET /v1/connect/googlesearchconsole`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/connect/googlesearchconsole`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Connect-Token`

Starts OAuth for Google Search Console. Each connected site becomes its own account with platform `googlesearchconsole`; it reads Google Search data and does not post.

Requested scope: `https://www.googleapis.com/auth/webmasters.readonly`.

### Flow

Redirect the user to `authUrl`.

- **One verified site:** Zernio connects it and redirects to `redirect_url` (or the dashboard) with `connected=googlesearchconsole`, `profileId`, `accountId` and `username` (the site, such as `acme.com`).
- **Several sites:** the user first picks one on a Zernio-hosted page, which then redirects the same way.

### Your own site picker

Add `headless=true` to `redirect_url`. Zernio then redirects there with `step=select_site`, `profileId`, `platform=googlesearchconsole` and a `pendingDataToken` for `GET /v1/connect/googlesearchconsole/sites` and `POST /v1/connect/googlesearchconsole/select-site`.

### Errors

On failure the redirect carries `error`, `platform=googlesearchconsole` and `error_message`. Errors include:

- `googlesearchconsole_scope_missing`: the user unticked Search Console access.
- `googlesearchconsole_no_sites`: the Google account has no verified Search Console site.
- `googlesearchconsole_no_refresh_token`: Google returned no refresh token; connect again.

## Query parameters

- `profileId` string, required
- `redirect_url` string
- `reconnectAccountId` string
- `welcome` boolean
- `brandName` string
- `logoUrl` string, uri
- `primaryColor` string
- `welcomeTheme` string

## Response `200`

OAuth authorization URL and authenticated state

- object
  - `authUrl` string, uri, required: Google URL to open in the user agent.
  - `state` string, required: Authenticated, expiring OAuth state handled by the callback.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `402`: Payment method or enterprise contract required: the authenticated account hit a billing gate before the connection could proceed. Switch on `reason` to render the right prompt: - `free_tier_exceeded`: the team has connected more accounts than the free tier allows. Add a payment method to continue (billed per additional connected account). - `twitter_passthrough`: connecting an X account requires a card on file, even the 1st one, because X API calls are passed through per call. Prepaid-balance accounts never get it: they pay X calls from the balance. - `enterprise_required`: the team's enterprise contract sets a connected-account cap and it has been reached. Self-service teams have NO cap (the $1/account rate continues at any scale). The user already has a card on file; this gate is about contract terms. - `card_verification_required`: the card on file was flagged at add time (prepaid, or issued in a different country than the billing address). A one-time verification charge of `details.verification_amount_cents` (USD) is pending; it is credited to the team's usage balance, not a fee. **What to do:** redirect the end-user to `dashboard_url`. - `free_tier_exceeded`, `twitter_passthrough`, `card_verification_required`: it opens the Zernio billing page (the add-payment-method drawer, or the verification step). The request succeeds once the card is on file (or verified, or paid). - `enterprise_required`: it opens the enterprise contact form (not the billing tab), to adjust the contract's limit.
- `403`: API key does not have access to this profile, or the key is read-only.
- `404`: Profile not found or access denied.
- `503`: Google Search Console OAuth is not configured.

## Changes

- **2026-11-18** `963da8e7a49f`: 5 info
  - added the new optional `query` request parameter `brandName`
  - added the new optional `query` request parameter `logoUrl`
  - added the new optional `query` request parameter `primaryColor`
  - added the new optional `query` request parameter `welcome`
  - …1 more
- **2026-11-18** `d79b66285ac5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/connect/googlesearchconsole/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/518557544cb4?raw)
