OAuth Clients

Use multiple OAuth client credentials (for different Google Cloud projects or brands) without mixing refresh tokens.

#How it works

Default client name: default
Default credentials file: $(os.UserConfigDir())/gogcli/credentials.json
Named credentials files: $(os.UserConfigDir())/gogcli/credentials-<client>.json
Tokens are stored per client (token:<client>:<email>). Default client also writes legacy keys for backwards compatibility.
Default account is stored per client, with a legacy global fallback for the default client.

#Selecting a client

Use --client (or GOG_CLIENT) to pick which credentials + token bucket to use:

gog --client work auth credentials ~/Downloads/work-client.json
gog --client work auth add you@company.com
gog --client work gmail search "is:unread"

When --client is not set, gog resolves the client in this order:

1) --client / GOG_CLIENT override 2) account_clients map in config 3) client_domains map in config 4) Credentials file named after the email domain (e.g. credentials-example.com.json) 5) default

#Domain auto-map

To auto-select a client for a domain:

gog --client work auth credentials ~/Downloads/work.json --domain example.com

This writes client_domains into config.json so any @example.com account selects the work client.

#Token errors

Command errors, per-item results, backup diagnostics, auth list --check, auth doctor --check, and watch/verbose error logs omit OAuth provider descriptions, URLs, and response bodies. Recognized errors retain their code and recovery steps. For invalid_grant, reauthorize the same account and client with gog --client <client> auth add <email>, preserving the services and scopes shown by gog auth list --json.

Automatic reauthorization keeps the command runtime and OAuth client dependencies when recovering from an expired or revoked token, so it can open the authorization flow and retry the original request. It preserves stored scope selections. Limited Gmail, Calendar read-only, and Photos read-only grants omit incremental authorization so Google does not add permissions from an earlier, broader grant. A Calendar read-only grant remains narrowed when combined with extra event-write scopes; a stored full Calendar grant retains incremental authorization.

#Listing stored credentials

gog auth credentials list

Shows stored credential files plus any configured domain mappings.

#Config example

{
  keyring_backend: "auto",
  account_clients: {
    "you@company.com": "work",
  },
  client_domains: {
    "example.com": "work",
  },
}

#Migration notes

Legacy token:<email> entries are copied to token:default:<email> the first time they are read.
Legacy default_account is still respected for the default client.
Browser, manual, remote, and account-manager authorization use S256 PKCE.

Manual state includes a short-lived verifier under the active gog config directory. Keep the same GOG_HOME and --client between remote steps.

Manual or remote authorization started before v0.24.0 cannot be completed

after upgrading. Run step 1 again to generate a PKCE-bound URL.

#Quota project

This selects request quota/billing attribution; it does not switch the Google login, grant IAM access, enable an API, or change a project's billing setup.

Some Google APIs reject ADC or direct access tokens when they cannot identify a quota project, even if the API is enabled in a project you control. Set --quota-project <project-id> or GOG_QUOTA_PROJECT to send that project in the X-Goog-User-Project header on authenticated Google API requests:

GOG_AUTH_MODE=adc gog --readonly --quota-project my-project calendar events
GOG_AUTH_MODE=adc GOG_QUOTA_PROJECT=my-project gog --readonly calendar events

The flag takes precedence over GOG_QUOTA_PROJECT. When both are unset, gog adds no quota-project header and existing authentication behavior is unchanged. GOOGLE_CLOUD_QUOTA_PROJECT and an ADC file's quota_project_id do not activate this setting; configure the flag or gog-specific variable explicitly.

The setting applies to stored OAuth, direct-token, ADC, and delegated service-account clients. A request's existing X-Goog-User-Project header takes precedence. Gmail watch request clients and MCP commands retain the selected project. API-key-only requests are unchanged.

The target API must be enabled on the project, and the authenticated principal needs serviceusage.services.use there, such as through roles/serviceusage.serviceUsageConsumer. See Google's quota-project requirements. This option does not grant IAM permissions or OAuth scopes, enable APIs, or configure billing. Credentials still need the command's API scopes; for example, ADC Calendar credentials need an appropriate Calendar scope independently of the quota project.

#Workspace service accounts

Workspace Admin, group, org-unit, and Keep automation commonly run through a service-account key with domain-wide delegation. Store the key for the Workspace admin identity you want to impersonate:

gog auth service-account set admin@example.com --key ~/Downloads/service-account.json
gog auth service-account status admin@example.com

File storage remains the default, and existing service-account key files keep working. To migrate a configured account to the keyring, pass its original JSON key file (or the currently stored key file) and add --keyring:

gog auth service-account set admin@example.com --key ~/Downloads/service-account.json --keyring
gog auth service-account status admin@example.com

This uses the same configured keyring backend as OAuth secrets. The managed service-account file becomes a reference; the key itself goes into the keyring. The generic legacy managed key file is removed after the reference is saved. Unmanaged input files and separately configured Keep-specific key files are left untouched. Secure or remove those copies yourself after verifying the migration. Keyring access is required whenever the account is used, including by Keep.

To return to file storage, run set with the original JSON key and omit --keyring. This also removes the old keyring entry. unset removes the managed reference and its keyring entry. Before using an older gog version or moving to another machine, restore file storage or provide the original key again; copying a reference file alone does not migrate its keyring entry. Keep a secure recovery copy of the original key until the migration is verified.

Cloud Identity Groups commands use the same Workspace service-account setup. Include https://www.googleapis.com/auth/cloud-identity.groups.readonly in domain-wide delegation, then run:

gog --account admin@example.com groups list
gog --account admin@example.com groups members engineering@example.com
gog --account admin@example.com calendar team engineering@example.com

Explicit --access-token and GOG_AUTH_MODE=adc auth remain available for advanced environments. groups list and Groups backups also require --account <workspace-email> because their transitive membership searches need the Workspace identity; groups members can use the active principal without that flag. calendar team shares the same Groups auth boundary. Stored user OAuth tokens are not used for these Cloud Identity lookups.

Then run Admin SDK commands with that account:

gog --account admin@example.com admin users create ada@example.com \
  --first-name Ada \
  --last-name Lovelace \
  --change-password

See Workspace Admin for user creation, organizational units, cleanup, and group examples.