What permissions does a Google Search Console API integration require?

A Google Search Console API integration normally requires OAuth 2.0 authorisation with the webmasters.readonly scope. This allows the integration to read approved Search Console data, such as search performance, site and sitemap information, without changing Search Console settings or submitting or deleting sitemaps. The Google account used to authorise the connection must also have access to every Search Console property you want to connect.

Required OAuth scope

The usual read-only scope is https://www.googleapis.com/auth/webmasters.readonly. It grants permission to view Search Console data through the API, including:

• Search Analytics data, such as clicks, impressions, click-through rate and average position, subject to the dimensions and date ranges supported by the API.
• The list of Search Console properties available to the authorised account.
• Property details and sitemap information that the relevant API methods expose.
• URL Inspection results where the integration and property support that request.

The scope does not, by itself, grant access to every website in Search Console. It only allows the integration to request data on behalf of the Google account that approved it.

When the broader scope is needed

An integration needs the broader https://www.googleapis.com/auth/webmasters scope when it must manage Search Console resources rather than only read them. Depending on the features provided, this could include submitting or deleting sitemaps, or making other changes supported by the Search Console API.

A reporting or SEO monitoring connection should use the read-only scope unless there is a clear requirement for write operations. Requesting the broader scope for a read-only workflow gives the integration more authority than it needs and can create unnecessary approval and security concerns.

Search Console property access

The authorising Google account must be a verified or otherwise authorised user of the relevant Search Console property. Its access level determines what the account can do in Search Console, while the OAuth scope determines what the application is allowed to request through the API. Both conditions must be satisfied.

For example, an account may successfully complete OAuth authorisation but still receive no usable data for a property if it has not been added to that property. Similarly, an account with access to one property will not automatically have access to another property in the same Google account.

Before connecting a property, check that:

• The correct Google account is being used during the authorisation process.
• The account has the appropriate Search Console user access for the property.
• The exact property is selected, including the correct domain property or URL-prefix property.
• The property has collected data for the period and dimensions being requested.

What the integration cannot do with read-only access

Read-only authorisation does not allow an integration to change verification settings, alter users, modify property configuration or perform write actions such as sitemap management. It also does not bypass Search Console’s data limitations, retention rules, permissions model or processing delays. An API response can therefore be empty or incomplete for a valid reason, even when the connection itself is working.

How authorisation works

1. The user selects the Google account that has access to the required Search Console properties.
2. Google displays the requested OAuth permissions, including whether access is read-only or includes management actions.
3. The user approves the request and returns to the SEO platform.
4. The platform uses the resulting authorisation to request Search Console data for properties that the Google account can access.

The integration should store access credentials securely and use them only for the agreed purpose. Access and refresh tokens should not be exposed in browser code, logs, support messages or shared spreadsheets. If the connection is no longer required, remove the integration’s access through the relevant Google account security controls and disconnect the account within the platform where that option is available.

Common permission problems

• Insufficient permission: the integration requested an operation that needs the broader management scope, or the Google account lacks the required property access.
• Property not found: the selected Google account cannot see the property, or the property address does not exactly match the one being requested.
• No data returned: the property may have no data for the selected date range, dimensions or search type, rather than having an authorisation fault.
• Connection works for one property but not another: access is granted per property, so the second property may need to be added to the Google account separately.
• Authorisation has expired or been revoked: reconnect the account and approve the requested scope again, then check that the correct Google account was selected.

For a standard SEO reporting integration, the recommended configuration is a dedicated, appropriately managed Google account with access to the required Search Console properties and the webmasters.readonly scope. Use the broader scope only when the integration genuinely needs to perform Search Console management actions, and review the requested permissions before approving the connection.