Google Workspace

Overview

Google mounts and the gws CLI accept an access token or OAuth refresh credentials. The steps below obtain refresh credentials for the services you enable.

Setup

1. Create a Google Cloud Project

Go to https://console.cloud.google.com/
Click the project selector dropdown -> New Project
Name it (e.g., “Mirage”) -> Create
Select it from the dropdown

2. Enable APIs

Go to https://console.cloud.google.com/apis/library

Enable the API for each service you plan to use:

Service	API to enable	Scope for Mirage’s read/write commands
Drive	Google Drive API	`https://www.googleapis.com/auth/drive`
Docs	Google Docs API	`https://www.googleapis.com/auth/documents`
Sheets	Google Sheets API	`https://www.googleapis.com/auth/spreadsheets`
Slides	Google Slides API	`https://www.googleapis.com/auth/presentations`
Gmail	Gmail API	`https://www.googleapis.com/auth/gmail.modify`
Calendar	Google Calendar API	`https://www.googleapis.com/auth/calendar`

Keep the Drive API and scope when using Google file mounts. The gws create commands also need Drive when placing new files inside a configured folder. For read-only use, select the corresponding read-only scopes.

3. Configure Google Auth Platform

The OAuth settings are under Google Auth Platform in the Cloud Console left sidebar (or go to https://console.cloud.google.com/auth/overview). A) Branding (left sidebar):

Fill in: App name (e.g., “Mirage”), support email, developer contact email
Save

B) Audience (left sidebar):

Set user type to External
Add your own Google email as a test user
Save

C) Data Access (left sidebar) - this is where scopes are configured:

Click Add or Remove Scopes
Add the scopes for the services you enabled in Step 2.
Select them -> Save

4. Create OAuth2 Client

Go to Clients in the left sidebar (or click Create OAuth client on the Overview page)
Application type: Desktop app
Name it -> Create
Copy the Client ID and Client Secret

5. Get the Refresh Token

A) Build and open the authorization URL. Replace YOUR_CLIENT_ID and add the scopes selected above to scope. This example requests Drive and Docs:

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:1&response_type=code&scope=https://www.googleapis.com/auth/drive%20https://www.googleapis.com/auth/documents&access_type=offline&prompt=consent

access_type=offline - required to receive a refresh token
prompt=consent - forces refresh token issuance on re-auth

B) Authorize: Sign in -> click through “unverified app” warning -> grant permissions. C) Copy the code: The browser redirects to http://localhost:1?code=4/0AXXXX... (page won’t load - expected). Copy the code value from the URL bar. D) Exchange for tokens:

curl -X POST https://oauth2.googleapis.com/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=THE_CODE_FROM_STEP_C" \
  -d "grant_type=authorization_code" \
  -d "redirect_uri=http://localhost:1"

The response JSON contains refresh_token - save it.

6. Save the credentials

# .env.development
GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPx-xxx
GOOGLE_REFRESH_TOKEN=1//0abc...

Token Lifetime

App Publishing Status	Typical behavior
Testing (default)	External-user grants expire after 7 days unless only basic profile scopes are requested
In production	Long-lived while the grant remains valid

You can complete setup in Testing mode. To publish, go to Audience and click Publish App. The TokenManager exchanges a valid refresh token for short-lived access tokens automatically. Refresh tokens can still be revoked or expire; repeat authorization when that happens. See Google’s token lifecycle documentation.

Troubleshooting

Issue	Fix
403 during OAuth flow	Add yourself as a test user under Audience
No `refresh_token` in response	Ensure `access_type=offline` and `prompt=consent` in the auth URL
Token exchange fails	`redirect_uri` must exactly match between auth URL and curl
Refresh token expires after 7 days	Publish the app under Audience, or re-authorize while testing
Auth code doesn’t work twice	Codes are single-use - re-authorize if exchange fails

For Python configuration, see Gmail, Drive, Docs, Sheets, Slides, and Calendar. For TypeScript configuration, see Gmail, Drive, Docs, Sheets, Slides, and Calendar. For Forms and service command trees, see GWS setup.

Getting Started

Examples

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Infrastructure

Configuration

Notifications

Help

Google Workspace

Overview

Setup

1. Create a Google Cloud Project

2. Enable APIs

3. Configure Google Auth Platform

4. Create OAuth2 Client

5. Get the Refresh Token

6. Save the credentials

Token Lifetime

Troubleshooting

​Overview

​Setup

​1. Create a Google Cloud Project

​2. Enable APIs

​3. Configure Google Auth Platform

​4. Create OAuth2 Client

​5. Get the Refresh Token

​6. Save the credentials

​Token Lifetime

​Troubleshooting

Overview

Setup

1. Create a Google Cloud Project

2. Enable APIs

3. Configure Google Auth Platform

4. Create OAuth2 Client

5. Get the Refresh Token

6. Save the credentials

Token Lifetime

Troubleshooting