Service Account Authentication

Service accounts provide non-interactive authentication for server-to-server workflows. Unlike user OAuth credentials, service accounts:

Don’t require browser-based login
Don’t expire (until the key is rotated)
Can use Domain-Wide Delegation to act on behalf of users
Are ideal for production automation and CI/CD

When to Use Service Accounts

Use service accounts when:

Running automated workflows that access Google Workspace data
Building applications that need to access resources across multiple user accounts
Deploying to production environments (servers, Kubernetes, Cloud Run)
You have a Google Workspace domain with admin access (required for Domain-Wide Delegation)

Use OAuth instead when:

Developing locally on your personal machine
Accessing only your own Google account
You don’t have Google Workspace admin permissions

Setup Overview

Create service account

Create a service account in Google Cloud Console and download the key file.

Enable Domain-Wide Delegation (optional)

If you need to access other users’ data, enable Domain-Wide Delegation in Google Workspace Admin.

Configure gws to use the service account

Point gws to the service account key file via environment variable.

Creating a Service Account

Open Google Cloud Console

Navigate to IAM & Admin > Service Accounts:

https://console.cloud.google.com/iam-admin/serviceaccounts?project=YOUR_PROJECT_ID

Create service account

Click Create Service Account
Service account name: gws-automation (or your preferred name)
Service account ID: gws-automation (auto-filled)
Description: “Service account for gws CLI automation”
Click Create and Continue
Skip granting roles (click Continue, then Done)

For Workspace APIs, service accounts don’t need IAM roles in the GCP project. Permissions are granted through OAuth scopes and Domain-Wide Delegation.

Create and download key

Click on the newly created service account
Go to the Keys tab
Click Add Key → Create new key
Select JSON format
Click Create

A JSON key file will be downloaded automatically.

The private key cannot be recovered if lost. Store it securely and never commit to version control.

Enable required APIs

Enable the Google Workspace APIs you need:

gcloud services enable drive.googleapis.com \
  gmail.googleapis.com \
  calendar-json.googleapis.com \
  sheets.googleapis.com \
  --project=YOUR_PROJECT_ID

Or enable via API Library.

Using the Service Account

Basic Usage (No Domain-Wide Delegation)

For APIs that don’t require user impersonation (e.g., accessing the service account’s own Drive):

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

The service account JSON file looks like:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "abc123...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "gws-automation@your-project.iam.gserviceaccount.com",
  "client_id": "123456789",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/..."
}

gws automatically detects service account credentials by the "type": "service_account" field.

With Domain-Wide Delegation (Impersonation)

To access another user’s data (e.g., read their Gmail, Drive files), you must:

Enable Domain-Wide Delegation for the service account
Grant OAuth scopes in Google Workspace Admin Console
Set the GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER environment variable

Enabling Domain-Wide Delegation

Domain-Wide Delegation requires Google Workspace Super Admin permissions. This feature is not available for personal Google accounts.

Enable Domain-Wide Delegation in GCP

Go to Service Accounts
Click on your service account
Click Show advanced settings
Under Domain-wide delegation, click Enable Google Workspace Domain-wide Delegation
Product name for consent screen: gws CLI
Click Save

Copy the Client ID (a long numeric string). You’ll need it in the next step.

Grant API scopes in Workspace Admin

Open Google Workspace Admin Console
Navigate to Security → Access and data control → API controls
Click Manage Domain Wide Delegation
Click Add new
Client ID: Paste the service account’s Client ID from step 1
OAuth scopes: Enter the scopes your automation needs (comma-separated):

https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar

Click Authorize

Test with impersonation

Set the user to impersonate:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=user@example.com

gws drive files list

This command will list Drive files as if you were user@example.com.

Common OAuth Scopes for Domain-Wide Delegation

Service	Scope
Google Drive (read/write)	`https://www.googleapis.com/auth/drive`
Google Drive (read-only)	`https://www.googleapis.com/auth/drive.readonly`
Gmail (read/write)	`https://www.googleapis.com/auth/gmail.modify`
Gmail (read-only)	`https://www.googleapis.com/auth/gmail.readonly`
Google Calendar	`https://www.googleapis.com/auth/calendar`
Google Sheets	`https://www.googleapis.com/auth/spreadsheets`
Google Docs	`https://www.googleapis.com/auth/documents`
Google Slides	`https://www.googleapis.com/auth/presentations`

You must list all scopes your automation will use in the Workspace Admin Console. Service accounts cannot request additional scopes at runtime.

CI/CD Integration

GitHub Actions

name: Service Account Automation

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM

jobs:
  workspace-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install gws
        run: npm install -g @googleworkspace/cli
      
      - name: Set up service account credentials
        run: |
          echo '${{ secrets.GWS_SERVICE_ACCOUNT }}' > /tmp/sa-key.json
      
      - name: Run automation as user
        env:
          GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /tmp/sa-key.json
          GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER: admin@example.com
        run: |
          gws drive files list --params '{"pageSize": 100}'

To set the secret:

Go to repo Settings → Secrets → Actions
Add GWS_SERVICE_ACCOUNT
Paste the entire contents of the service account JSON file

Docker

FROM node:20-alpine

RUN npm install -g @googleworkspace/cli

COPY service-account.json /app/service-account.json

ENV GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/app/service-account.json
ENV GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com

CMD ["gws", "drive", "files", "list"]

Build and run:

docker build -t gws-automation .
docker run gws-automation

Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: gws-service-account
type: Opaque
stringData:
  key.json: |
    {
      "type": "service_account",
      "project_id": "your-project",
      ...
    }
---
apiVersion: batch/v1
kind: CronJob
metadata:
  name: workspace-sync
spec:
  schedule: "0 9 * * 1"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: gws
            image: node:20-alpine
            command: ["/bin/sh", "-c"]
            args:
              - |
                npm install -g @googleworkspace/cli
                gws drive files list --params '{"pageSize": 100}'
            env:
            - name: GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
              value: /secrets/key.json
            - name: GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER
              value: admin@example.com
            volumeMounts:
            - name: service-account
              mountPath: /secrets
              readOnly: true
          volumes:
          - name: service-account
            secret:
              secretName: gws-service-account
          restartPolicy: OnFailure

Environment Variables Reference

Variable	Description	Example
`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`	Path to service account JSON	`/app/service-account.json`
`GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER`	User email to impersonate (requires DWD)	`admin@example.com`

Security Best Practices

Restrict service account permissions

Grant the minimum OAuth scopes required in Workspace Admin
Use separate service accounts for different automation workflows
Regularly audit service account usage in the Admin Console

Secure the private key

Never commit service account keys to version control
Store keys in encrypted secrets managers (GitHub Secrets, Vault, Cloud Secret Manager)
Rotate keys every 90 days
Delete unused service account keys immediately

Use impersonation narrowly

Only impersonate the specific users required
Avoid impersonating super admin accounts
Log all impersonated actions for audit trails

Monitor usage

Enable audit logging in Google Workspace Admin
Set up alerts for unexpected API usage
Review service account activity monthly

Troubleshooting

”Subject (user to impersonate) is required” Error

You’re trying to access user data without setting GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER:

export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=user@example.com

“Not authorized to access this resource” Error

Possible causes:

Domain-Wide Delegation not enabled: Follow steps in “Enabling Domain-Wide Delegation”
Scopes not granted in Workspace Admin: Verify scopes in Admin Console → Security → API Controls → Domain Wide Delegation
Wrong Client ID: Ensure you used the service account’s Client ID (not the numeric User ID)
API not enabled: Enable required APIs in GCP Console

”Invalid JWT Signature” Error

The service account key file is corrupted or invalid:

Re-download the JSON key from GCP Console
Verify the file contains -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----
Check that the file wasn’t modified (no extra whitespace, encoding issues)

Credential Precedence

When both user OAuth and service account credentials are available:

GOOGLE_WORKSPACE_CLI_TOKEN (pre-obtained access token, highest priority)
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE (can be user OAuth or service account)
Encrypted user credentials (~/.config/gws/credentials.enc)
Plaintext user credentials (~/.config/gws/credentials.json)

gws detects service account vs user OAuth by inspecting the "type" field in the JSON file.

Comparison: Service Accounts vs User OAuth

Feature	Service Account	User OAuth
Setup complexity	High (requires Workspace admin)	Low (just `gws auth login`)
Requires browser	No	Yes (for initial setup)
Credential lifetime	Until key is rotated	Until refresh token revoked
Access multiple users	Yes (with DWD)	No (only authenticated user)
Works in CI/CD	Yes	Yes (after export)
Audit trail	Service account name	User email
Best for	Production automation	Local development

Get Started

Core Concepts

Authentication

Command Reference

Advanced Usage

AI Integration

Development

Troubleshooting

When to Use Service Accounts

Setup Overview

Creating a Service Account

Using the Service Account

Basic Usage (No Domain-Wide Delegation)

With Domain-Wide Delegation (Impersonation)

Enabling Domain-Wide Delegation

Common OAuth Scopes for Domain-Wide Delegation

CI/CD Integration

GitHub Actions

Docker

Kubernetes Secret

Environment Variables Reference

Security Best Practices

Troubleshooting

”Subject (user to impersonate) is required” Error

“Not authorized to access this resource” Error

”Invalid JWT Signature” Error

Credential Precedence

Comparison: Service Accounts vs User OAuth

Next Steps

Headless/CI Auth

Interactive Auth

Get Started

Core Concepts

Authentication

Command Reference

Advanced Usage

AI Integration

Development

Troubleshooting

​When to Use Service Accounts

​Setup Overview

​Creating a Service Account

​Using the Service Account

​Basic Usage (No Domain-Wide Delegation)

​With Domain-Wide Delegation (Impersonation)

​Enabling Domain-Wide Delegation

​Common OAuth Scopes for Domain-Wide Delegation

​CI/CD Integration

​GitHub Actions

​Docker

​Kubernetes Secret

​Environment Variables Reference

​Security Best Practices

​Troubleshooting

​”Subject (user to impersonate) is required” Error

​“Not authorized to access this resource” Error

​”Invalid JWT Signature” Error

​Credential Precedence

​Comparison: Service Accounts vs User OAuth

​Next Steps

Headless/CI Auth

Interactive Auth

When to Use Service Accounts

Setup Overview

Creating a Service Account

Using the Service Account

Basic Usage (No Domain-Wide Delegation)

With Domain-Wide Delegation (Impersonation)

Enabling Domain-Wide Delegation

Common OAuth Scopes for Domain-Wide Delegation

CI/CD Integration

GitHub Actions

Docker

Kubernetes Secret

Environment Variables Reference

Security Best Practices

Troubleshooting

”Subject (user to impersonate) is required” Error

“Not authorized to access this resource” Error

”Invalid JWT Signature” Error

Credential Precedence

Comparison: Service Accounts vs User OAuth

Next Steps