Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Google resources use OAuth2 with a refresh token to authenticate against:
  • Google Drive API v3 - lists documents, reads metadata
  • Google Docs API v1 - reads/writes document content
Authentication requires three values: client_id, client_secret, and refresh_token.

​
Setup

​
1. Create a Google Cloud Project

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

​
2. Enable APIs

  1. Go to https://console.cloud.google.com/apis/library
  2. Search Google Drive API -> click -> Enable
  3. Search Google Docs API -> click -> Enable

​
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):
  1. Fill in: App name (e.g., “Mirage”), support email, developer contact email
  2. Save
B) Audience (left sidebar):
  1. Set user type to External
  2. Add your own Google email as a test user
  3. Save
C) Data Access (left sidebar) - this is where scopes are configured:
  1. Click Add or Remove Scopes
  2. Search for or paste these scopes:
    • https://www.googleapis.com/auth/drive (full Drive access)
    • https://www.googleapis.com/auth/documents (Google Docs)
    • https://www.googleapis.com/auth/presentations (Google Slides)
  3. Select them -> Save
D) Publish (to avoid 7-day token expiry):
  1. Go to Audience -> click Publish App
  2. See Token Lifetime for details

​
4. Create OAuth2 Client

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

​
5. Get the Refresh Token

A) Open this URL in a browser (replace YOUR_CLIENT_ID): 
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%20https://www.googleapis.com/auth/presentations&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. Set Environment Variables

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

​
Token Lifetime

App Publishing StatusRefresh Token Lifetime
Testing (default)7 days - must re-authorize
In ProductionNever expires (with continued use)
To publish: go to the OAuth consent screen page and click Publish App. Users will see an “unverified app” warning during auth, which is fine for personal use. A published refresh token only gets revoked if: For personal use with a published app, you do the auth flow once and it works indefinitely. The TokenManager in the resource automatically uses the refresh token to obtain fresh access tokens (which expire hourly) behind the scenes.

​
Scopes Reference

ScopePurpose
https://www.googleapis.com/auth/driveFull Drive access (list, create, delete files)
https://www.googleapis.com/auth/drive.readonlyList files, read metadata only (alternative)
https://www.googleapis.com/auth/documentsRead and write Google Docs
https://www.googleapis.com/auth/documents.readonlyRead-only Docs access (alternative)
https://www.googleapis.com/auth/presentationsRead and write Google Slides

​
Troubleshooting

IssueFix
403 during OAuth flowAdd yourself as a test user in Step 3.7
No refresh_token in responseEnsure access_type=offline and prompt=consent in the auth URL
Token exchange failsredirect_uri must exactly match between auth URL and curl
Refresh token expires after 7 daysPublish the app (Step 3.9)
Auth code doesn’t work twiceCodes are single-use - re-authorize if exchange fails
For Python configuration, see the Python Google Workspace Setup guide.