# Connect

Connect a Search Console site to a profile with Google sign-in, from the dashboard or with the connect API.

## Connect a Search Console site

Request the authorization link for a profile, then send the user to `authUrl`:

```bash
curl "https://zernio.com/api/v1/connect/googlesearchconsole?profileId=PROFILE_ID&redirect_url=https://example.com/done" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

```json
{ "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=…", "state": "…" }
```

The user signs in with Google and allows read access to Search Console. Zernio offers only the verified sites the account can read (owner, full or restricted user).

What happens next depends on how many there are:

- **One site**: Zernio connects it straight away.
- **Several sites**: 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=googlesearchconsole`, `profileId`, `accountId` and `username` (the site, such as `acme.com`).

A site is either a Domain property, written `sc-domain:acme.com`, or a URL-prefix property, written as the full prefix such as `https://acme.com/`.

## Show your own site picker

To keep users in your app when they can read several sites, add `headless=true` to `redirect_url`. Instead of Zernio's page, Zernio redirects to your `redirect_url` with `step=select_site`, `profileId`, `platform=googlesearchconsole` and a `pendingDataToken`.

List the sites with that token and show them in your own UI:

```bash
curl "https://zernio.com/api/v1/connect/googlesearchconsole/sites?pendingDataToken=TOKEN" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

```json
{
  "sites": [
    { "siteUrl": "sc-domain:acme.com", "permissionLevel": "siteOwner" },
    { "siteUrl": "https://blog.acme.com/", "permissionLevel": "siteFullUser" }
  ]
}
```

Then connect the one the user picks, and send the user to the returned `redirect_url`:

```bash
curl -X POST "https://zernio.com/api/v1/connect/googlesearchconsole/select-site" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pendingDataToken": "TOKEN", "siteUrl": "sc-domain:acme.com" }'
```

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 site never reaches this step: it connects straight away.

## Connect more than one site

Each connected site is one account. To read another site, connect it to a different profile. List the connected sites with `GET /v1/accounts?category=analytics`.

## How it behaves

- Zernio asks only for `https://www.googleapis.com/auth/webmasters.readonly`. It cannot change the site, submit sitemaps or request indexing.
- 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=googlesearchconsole` and `error_message`.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| `googlesearchconsole_access_denied` | The user declined on Google's consent screen | Start the connect again and allow access. |
| `googlesearchconsole_scope_missing` | The user unticked the Search Console permission | Start the connect again and keep the permission ticked. |
| `googlesearchconsole_no_sites` | The Google account has no verified Search Console site | Add and verify the site in Search Console, or get access to one, then connect again. |
| `googlesearchconsole_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. |
| `googlesearchconsole_invalid_state` | The link expired or was already used | Request a fresh `authUrl`. |
| `googlesearchconsole_auth_failed` | Google returned to Zernio without an authorization code | Start the connect again; contact support if it repeats. |
| `googlesearchconsole_connection_failed` | Google refused the code exchange, or the site could not be read or saved | Start the connect again; contact support if it repeats. |
| `503` on `GET /v1/connect/googlesearchconsole` | Google Search Console is not configured on this Zernio environment | Contact support. |

## Related

- [Get Google Search Console connect URL](/connect/get-google-search-console-connect-url)
- [List Search Console sites](/connect/list-google-search-console-sites)
- [Select a Search Console site](/connect/select-google-search-console-site)
- [List accounts](/accounts/list-accounts)
- [Reports](/platforms/google-search-console/reports)