Authentication

Search Console data belongs to a Google account, so every request needs an OAuth access token. API keys do not work for this API, and Google's device-code flow does not allow Search Console scopes. gsc supports every other way to get a token.

Credential precedenceCopy Anchor Link

Every command uses the first of: --access-token / GSC_ACCESS_TOKEN, then --credentials / GSC_CREDENTIALS, then the selected profile. Profiles are chosen by --profile, then GSC_PROFILE, then the saved default. gsc never falls back to ambient Application Default Credentials on its own, so an agent never runs as an identity nobody chose.

Browser loginCopy Anchor Link

$ gsc auth login
Opening your browser to sign in. If it does not open, visit:
  https://accounts.google.com/o/oauth2/v2/auth?...
Logged in as me@example.com (profile "default").
Found 3 properties. Default site set to sc-domain:example.com (change with: gsc sites use SITE).

1. gsc listens on 127.0.0.1 on a free port and opens Google's consent page (PKCE S256, a random state, offline access). The URL is printed to stderr in case the browser does not open.
2. Approve access on Google's consent screen. The tab then confirms you are signed in; close it and return to the terminal.
3. The refresh token is saved in the OS keychain (macOS Keychain, Windows Credential Manager, or the Secret Service on Linux). Access tokens refresh automatically from then on. Keychain entries are namespaced by config file, so same-named profiles in different configs (GSC_CONFIG or a custom XDG_CONFIG_HOME) never overwrite each other.
4. gsc lists your properties once and picks a default site: the only property, or your choice from a list. When it cannot ask (for example a service account or ADC login with --no-input), it picks the first domain property. --no-verify skips this call.

gsc asks Google for Search Console access (https://www.googleapis.com/auth/webmasters) plus openid and email, which let it show the signed-in account. What it does with that access is in the privacy policy.

Options:

• --profile NAME saves under a named profile (default: the current profile, or default).
• --scope readonly requests webmasters.readonly only. Write commands then stop early with a message. The default full scope covers every command; --read-only still blocks writes for agents.
• --insecure-storage keeps the token in secrets.yaml (mode 0600) next to the config instead of the keychain. Google's OAuth policy asks for encrypted storage, so use it only where no keychain exists. Without the flag, a missing keychain stops the login (and asks first when you are at a terminal).

Run gsc auth login again any time Google revokes access; errors say exactly which command to run.

The built-in OAuth client is added to release builds when they are built; gsc version -o json reports builtin_oauth_client for the binary you have. Everyone using it shares one Google Cloud project's quota, so heavy users should bring their own client or a service account.

Headless loginCopy Anchor Link

For a machine without a browser:

1. Run gsc auth login --no-browser and open the printed URL on any device.
2. Approve access. The browser then tries to load http://127.0.0.1:8085/?code=... and fails. That is expected.
3. Copy the full address from the browser and paste it into the terminal.

This uses the same loopback redirect and PKCE as the normal flow. It is not Google's retired out-of-band (copy-a-code) flow.

Your own OAuth clientCopy Anchor Link

1. In Google Cloud Console, create or pick a project and enable the Google Search Console API.
2. Configure the OAuth consent screen (External or Internal), then create an OAuth client of type Desktop app and download its JSON.
3. Run gsc auth login --client-secret-file client_secret_XXXX.json.

Alternatively set GSC_CLIENT_ID and GSC_CLIENT_SECRET, which override the built-in client for every login. Each profile records which client it used, so refreshes always use the same one. Keep the consent screen In production: Google expires refresh tokens after 7 days for apps left in Testing.

Service accountsCopy Anchor Link

1. In Google Cloud Console, enable the Search Console API, create a service account, and create a JSON key.
2. In Search Console, open the property, then Settings > Users and permissions > Add user, and add the service account email (...@...iam.gserviceaccount.com) with Full permission (Owner only if you need owner-only actions).
3. Run gsc auth login --profile ci --service-account /path/key.json.

gsc stores the key file path, not the key. Google Workspace admins can use domain-wide delegation with --subject user@yourdomain.com; the impersonated user must have access to the property.

For a single command without a profile: GSC_CREDENTIALS=/path/key.json gsc performance -s ....

Application Default Credentials and impersonationCopy Anchor Link

gsc auth login --adc saves a profile that resolves Google's Application Default Credentials when a command runs: GOOGLE_APPLICATION_CREDENTIALS, the gcloud ADC file, workload identity federation, or the GCE and Cloud Run metadata server.

gcloud's own client is meant for Google Cloud scopes, so log in with your Desktop client and the Search Console scope:

gcloud auth application-default login \
  --client-id-file=client_secret.json \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/webmasters.readonly
gsc auth login --profile gcloud --adc

Keyless CI (for example GitHub Actions with google-github-actions/auth): give the federated identity roles/iam.serviceAccountTokenCreator on a service account, add that service account to the Search Console property, then:

gsc auth login --profile ci --adc --impersonate reporting@my-project.iam.gserviceaccount.com --no-verify

Raw access tokensCopy Anchor Link

GSC_ACCESS_TOKEN=$(gcloud auth print-access-token) gsc sites list works with any token that carries a Search Console scope. Nothing is stored and nothing refreshes. gsc auth token prints the current profile's token for debugging; treat it as a secret.

Status, profiles, and logoutCopy Anchor Link

gsc auth status            # which credential is in use, from local config only
gsc auth status --verify   # also lists properties once
gsc auth list              # profiles, without secrets
gsc auth use work          # switch the default profile
gsc auth logout            # delete this profile and its token locally
gsc auth logout --revoke   # also revoke at Google (asks; --yes to skip)

--revoke is opt-in because Google revokes the account's tokens for every client in the OAuth project, which signs out every other machine and profile using the same client. You can also remove access from your Google Account at myaccount.google.com/permissions.

--read-only blocks every command that changes local credentials or configuration, as well as remote writes; tokens refreshed in read-only mode stay in memory. gsc login and gsc status are aliases of gsc auth login and gsc auth status, and gsc config show, config list-profiles, and config use-profile match the other CLIs in the suite.

TroubleshootingCopy Anchor Link