Authentication

Commands select credentials in this order:

  1. GOOGLE_SERVICE_ACCOUNT_JSON, containing a service-account JSON document.
  2. An explicitly set GOOGLE_APPLICATION_CREDENTIALS file.
  3. A matching local native OAuth record for the current tool and access tier.
  4. Ambient Application Default Credentials (ADC).

The explicit file and ambient ADC can represent any Google-supported credential type, including service accounts, user credentials, workload identity, or an attached identity. A configured environment source or marked native record fails closed if it is invalid; the command does not silently choose a different identity.

Credential precedence

Choose native OAuth for an interactive desktop user, or use operator-managed service accounts and ADC for automation. Native OAuth records are separate records for each tool + access-tier pair: a gtmctl containers record is not a gtmctl versions record, nor a record for either GA4 tool.

OAuth consent and credential selection only determine which identity and OAuth scope the CLI presents. They do not grant access to Analytics properties or Tag Manager resources. Grant that authenticated principal the required Google Analytics, Tag Manager, and IAM resource permissions separately.

The legal native OAuth tiers and their scopes are:

ToolAccess tierScope
ga4datactlreadhttps://www.googleapis.com/auth/analytics.readonly
ga4adminctlreadhttps://www.googleapis.com/auth/analytics.readonly
ga4adminctledithttps://www.googleapis.com/auth/analytics.edit
gtmctlreadhttps://www.googleapis.com/auth/tagmanager.readonly
gtmctlusershttps://www.googleapis.com/auth/tagmanager.manage.users
gtmctlaccountshttps://www.googleapis.com/auth/tagmanager.manage.accounts
gtmctlcontainershttps://www.googleapis.com/auth/tagmanager.edit.containers
gtmctlversionshttps://www.googleapis.com/auth/tagmanager.edit.containerversions
gtmctlpublishhttps://www.googleapis.com/auth/tagmanager.publish
gtmctldeletehttps://www.googleapis.com/auth/tagmanager.delete.containers

Use <tool> auth --help to see the installed tool’s legal --access values. Choose a tier from the operation mapping in the relevant tool guide, not from a simple read/write/delete assumption.

Native OAuth storage

Native OAuth stores refresh material, client ID, client secret, and the selected scope binding only in an approved encrypted OS keyring: macOS Keychain, Windows Credential Locker, or Linux Secret Service. There is no plaintext fallback. Access tokens are refreshed only in memory, and the stored scope is not proof of a scope Google still grants.

Headless Linux commonly has no approved keyring; use externally managed ADC there. ADC files, including gcloud-managed credentials, are outside the CLI’s native encrypted-keyring guarantee and must be secured by the operator. On Windows, a native record is limited by Credential Locker’s 2,560-byte UTF-16LE value limit.

Before changing a native record, the CLI writes a non-secret local marker. A missing or invalid marked record does not fall through to ADC. Recover incomplete or interrupted local storage with auth forget, then log in again.

Record lifecycle

Use the selected tool and tier for each command:

ga4datactl auth status --access read
ga4datactl auth forget --access read
ga4datactl auth revoke --access read --apply --acknowledge-project-wide-revocation

auth status checks the selected local record without contacting Google. auth forget deletes only that local record; it does not revoke Google access. auth revoke revokes the user’s grant across the OAuth project and then removes the selected local record, so it is not a tier-local remote logout. Alternatively, revoke the grant in Google Account permissions and run auth forget locally.

For an interactive login, follow Desktop OAuth setup.

Backward Installation Desktop OAuth setup Forward