Index of every page on this site: llms.txt
Skip to content

Set up keys and scopes for hosted data

Hosted v1 checks the credential class, required scope, and resource ownership for each operation.

Choose a credential class

ClassUsed byAccess
User API keyYour own server integrationIts user and authorized Sites
Partner keyA linked partner integrationLinked users, Teams, and authorized Sites

The hosted HTTP specification publishes each operation's security, x-gscdump-scopes, and x-gscdump-ownership fields.

Create and store a user API key

Self-service key

Generate the key in Agent setup. Copy it once and store it in a server secret store. User keys have a fixed scope set. You do not select scopes during creation.

Partner-issued key

A partner can create a key for a linked user with createUserApiKey. This method requires a partner key and users:write; it is not a user self-service SDK call.

Send the key as Authorization: Bearer <key>. The SDK does this through credential: () => key. Never put a key in a URL, browser bundle, browser storage, WebSocket frame, or log.

Check scope and Site ownership

OperationScopeResource check
queryAnalyticsRowsanalytics:executeAuthorized Site
getSiteIndexingindexing:readAuthorized Site
inspectSiteUrlsindexing:writeAuthorized Site
getSiteSitemapssitemaps:readAuthorized Site

An allowed scope alone does not grant a different Site. Use its exact siteId.

Rotate or revoke a key

Add a new key to the server secret store, deploy it, then revoke the old key. A partner can use its partner-only key methods for keys it issued. Check active clients before revocation.

Diagnose forbidden access

For 401, check that the Bearer key is present and active. For 403, check the operation's credential class, scope, Site ownership, and Site ID. Include the request ID in support reports. See Errors and retry.