Skip to main content

​
Overview

Authentication errors occur when the CLI cannot obtain or use valid credentials to access Google Workspace APIs. This guide covers common authentication problems and their solutions.

​
Common OAuth Errors

Cause: Your OAuth refresh token has expired or been revoked.Solution: Re-authenticate with the CLI:
gws auth login
If the error persists, remove existing credentials and start fresh:
rm ~/.config/gws/credentials.json
gws auth login
Note: Credentials are encrypted and stored in your OS keyring. The plaintext file at ~/.config/gws/credentials.json is a fallback.
Cause: The OAuth client secret is missing, malformed, or doesn’t match your Google Cloud project.Solution:
  1. Verify ~/.config/gws/client_secret.json exists and contains valid OAuth client credentials
  2. Re-download the client secret from Google Cloud Console
  3. Ensure you created a Desktop app OAuth client (not Web application)
  4. Save the downloaded JSON to ~/.config/gws/client_secret.json
  5. Run gws auth login again
Cause: The OAuth client is configured for the wrong redirect URI.Solution: The CLI uses http://localhost:PORT for OAuth callbacks. Ensure your OAuth client includes http://localhost in its authorized redirect URIs:
  1. Go to Credentials
  2. Edit your OAuth 2.0 Client ID
  3. Add http://localhost to Authorized redirect URIs (the CLI will use an ephemeral port)
  4. Save and retry gws auth login
Cause: Your OAuth consent screen is in testing mode and hasn’t been verified by Google.Solution: This is normal for personal projects. Click Continue to proceed.If you see scope checkboxes after clicking Continue, select all required scopes (or click Select all) before proceeding.Publishing your app: If you need to remove this warning, submit your app for OAuth verification. This is only necessary for apps used by external users.

​
Token Expiration Issues

​
Symptom: Commands Fail After Working Previously

If commands worked before but now return 401 Unauthorized: 
{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials."
  }
}
Solution: Your access token has expired. The CLI should automatically refresh it, but if that fails: 
gws auth login

​
Using Pre-obtained Tokens

If you’re using GOOGLE_WORKSPACE_CLI_TOKEN with a pre-obtained access token: 
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
Remember:
  • Access tokens expire after 1 hour
  • You must refresh the token before expiration
  • The CLI cannot auto-refresh tokens set via environment variable

​
Invalid Credentials

​
Error: Credentials File Not Found

Error: No credentials found. Please run 'gws auth login' first.
Solution: You haven’t authenticated yet: 
gws auth setup  # First-time setup
# OR
gws auth login  # If OAuth client already exists

​
Error: Malformed Credentials JSON

Error: Failed to parse credentials file
Solution: Your credentials file is corrupted:
  1. Remove the corrupted file: 
    rm ~/.config/gws/credentials.json
  2. Re-authenticate: 
    gws auth login

​
Permission Issues

​
Error: Insufficient Permission (403)

{
  "error": {
    "code": 403,
    "message": "Insufficient Permission",
    "reason": "forbidden"
  }
}
Causes:
  1. Your OAuth token doesn’t include the required scope
  2. Your account doesn’t have permission to access the resource
  3. You need domain-wide delegation (for service accounts)
Solutions:
  1. Missing OAuth scopes: Re-authenticate to request additional scopes: 
    gws auth login
    Select all required scopes when prompted.
  2. Account permissions: Verify your Google Workspace account has the necessary permissions (e.g., Admin role for Admin SDK operations).
  3. Service account delegation: If using a service account, ensure domain-wide delegation is configured: 
    export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com

​
Re-authenticating

To completely reset your authentication: 
# Remove all credentials
rm ~/.config/gws/credentials.json
rm ~/.config/gws/client_secret.json

# Start fresh
gws auth setup

​
Debugging Tips

​
Check Credential Precedence

The CLI uses credentials in this order:
  1. GOOGLE_WORKSPACE_CLI_TOKEN (access token)
  2. GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE (credentials file path)
  3. Encrypted credentials in OS keyring
  4. ~/.config/gws/credentials.json (plaintext fallback)
To debug, check which credential source is active: 
env | grep GOOGLE_WORKSPACE_CLI

​
Verify OAuth Client Configuration

Your ~/.config/gws/client_secret.json should look like: 
{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}
Note: The "installed" key indicates a Desktop app OAuth client.

​
Test with Dry Run

Verify authentication without making actual API calls: 
gws drive files list --params '{"pageSize": 1}' --dry-run
This will show the request details without executing it.

​
Headless/CI Environments

Authentication errors are common in headless environments (servers, CI/CD).

​
Export Credentials from Local Machine

  1. Authenticate on a machine with a browser: 
    gws auth login
  2. Export credentials: 
    gws auth export --unmasked > credentials.json
  3. On the headless machine: 
    export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list

​
Service Account Authentication

For server-to-server authentication: 
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list
No gws auth login required.

​
Still Having Issues?

If authentication continues to fail:
  1. Check the Common Issues guide
  2. Review the Authentication documentation
  3. File an issue on GitHub with:
    • The exact error message (redact sensitive info)
    • Your OS and CLI version (gws --version)
    • Authentication method (OAuth, service account, etc.)