Skip to main content
Interactive authentication is the recommended approach for local development. It uses OAuth 2.0 with a browser-based consent flow and stores credentials encrypted at rest.

​
Quick Start

For first-time setup (creates GCP project, enables APIs, and logs you in): 
gws auth setup
For subsequent logins: 
gws auth login

​
Prerequisites

The gws auth setup command requires the gcloud CLI to be installed and authenticated.
Install gcloud CLI: 
# macOS
brew install google-cloud-sdk

# Linux
curl https://sdk.cloud.google.com | bash

# Windows
choco install gcloudsdk
Authenticate gcloud: 
gcloud auth login

​
First-Time Setup

1

Run auth setup

The gws auth setup command automates the entire OAuth configuration process:
gws auth setup
This command will:
  • Create a new Google Cloud project (or use an existing one with --project)
  • Enable required Google Workspace APIs
  • Create an OAuth 2.0 Desktop App client
  • Download the client credentials
  • Trigger the OAuth login flow
2

Select scopes

You’ll be prompted to select OAuth scopes in an interactive picker:
  • Recommended (default): Non-restricted scopes + read-only scopes
  • Read Only: Only read-only scopes for enabled APIs
  • Full Access: All scopes including restricted ones (may require app verification)
  • Custom: Select individual scopes manually
Use arrow keys to navigate, Space to toggle, Enter to confirm.
3

Authorize in browser

A browser window will open with the OAuth consent screen.
If you see “Google hasn’t verified this app”, click Continue. This is normal for personal GCP projects in testing mode.
  • Select your Google account
  • Review and approve the requested scopes
  • The page will redirect to localhost and display “Authentication complete”
4

Verify authentication

Check your authentication status:
gws auth status
Example output:
{
  "auth_method": "oauth2",
  "storage": "encrypted",
  "encrypted_credentials": "/home/user/.config/gws/credentials.enc",
  "encrypted_credentials_exists": true,
  "encryption": "AES-256-GCM",
  "user": "you@example.com",
  "scopes": [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/gmail.modify"
  ]
}

​
Subsequent Logins

Once you’ve run gws auth setup, use gws auth login for future authentications: 
gws auth login
This reuses the saved OAuth client configuration from ~/.config/gws/client_secret.json and only requires browser authentication.

​
Scope Options

# Request read-only scopes
gws auth login --readonly

# Request all scopes (including restricted ones)
gws auth login --full

# Request custom scopes
gws auth login --scopes https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/gmail.readonly

​
Security Model

​
Credential Encryption

Credentials are encrypted at rest using AES-256-GCM. The encryption key is stored securely:
  1. Primary: OS Keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
  2. Fallback: Local file ~/.config/gws/.encryption_key with 0600 permissions (Unix)
The encrypted credentials file is stored at: 
~/.config/gws/credentials.enc

​
What’s Stored

The encrypted credentials file contains:
  • OAuth client ID
  • OAuth client secret
  • Refresh token (used to obtain new access tokens)
Access tokens are cached separately in ~/.config/gws/token_cache.json (also encrypted) and automatically refreshed when expired.

​
File Permissions

On Unix systems, gws automatically sets secure permissions:
  • Config directory: 0700 (user-only access)
  • Credentials files: 0600 (user read/write only)
  • Encryption key file: 0600

​
Checking Authentication Status

View detailed authentication information: 
gws auth status
This displays:
  • Authentication method (OAuth2 or service account)
  • Storage type (encrypted, plaintext, or none)
  • Credential source (env var, file, or OS keyring)
  • User email (if logged in)
  • Granted OAuth scopes
  • Enabled APIs in your GCP project
  • Token validity

​
Exporting Credentials

For debugging or to transfer credentials to another machine: 
# Export with masked secrets
gws auth export

# Export unmasked (for CI/headless use)
gws auth export --unmasked > credentials.json
The --unmasked flag outputs your client secret and refresh token in plaintext. Handle this file carefully and never commit it to version control.

​
Logging Out

Remove all saved credentials and token caches: 
gws auth logout
This deletes:
  • ~/.config/gws/credentials.enc
  • ~/.config/gws/credentials.json (if present)
  • ~/.config/gws/token_cache.json
The OAuth client configuration (client_secret.json) is preserved so you can run gws auth login again without repeating the full setup.

​
Troubleshooting

​
”Google hasn’t verified this app” Warning

This is normal for OAuth apps in testing mode. Click Continue to proceed. To remove this warning:
  1. Complete the OAuth app verification process
  2. Or add your email to the test users list in the OAuth consent screen

​
”restricted_client” Error

Some scopes (e.g., cloud-platform, pubsub) require app verification or are restricted for personal accounts. Solution:
  • Use gws auth login without --full (defaults to safe scopes)
  • Or verify your OAuth app in Google Cloud Console
  • Or use a Google Workspace account with appropriate admin permissions

​
Decryption Failed

If you see “Decryption failed” errors: 
gws auth logout
gws auth login
This can happen if:
  • Credentials were created on a different machine
  • The OS keyring was reset or is unavailable
  • The .encryption_key file was deleted

​
Next Steps

Headless/CI Setup

Export credentials for CI/CD environments

Manual OAuth Setup

Configure OAuth clients manually in Google Cloud Console