nself-google: Google Workspace Integration

Connect your nself backend to Google Workspace. Read and send Gmail, manage Google Calendar events, browse Google Drive files, and read and write Google Sheets, all through a single OAuth flow stored server-side.

Install

nself license set nself_pro_...
nself plugin install google
nself build
nself start

OAuth Setup

1. Go to Google Cloud Console and create or select a project.
2. Enable the APIs you need: Gmail API, Google Calendar API, Google Drive API, Google Sheets API.
3. Go to APIs & Services > Credentials and create an OAuth 2.0 Client ID (type: Web application). Set the redirect URI to https://your-domain.com/google/auth/callback.
4. Copy the Client ID and Client Secret into your .env.

Configuration

Environment Variables

PLUGIN_GOOGLE_CLIENT_ID=123456789-xxxxx.apps.googleusercontent.com
PLUGIN_GOOGLE_CLIENT_SECRET=GOCSPX-xxxxx

Quick Start

Authorize a User

# Step 1: Get the OAuth URL (include the user_id you want to link)
curl "http://127.0.0.1:3719/google/auth/url?user_id=user-uuid"
# Returns: { "url": "https://accounts.google.com/o/oauth2/..." }

# Step 2: Redirect the user to that URL
# Step 3: After consent, Google redirects to /google/auth/callback
# The plugin stores the refresh token automatically, no further action needed

Use the APIs

# List Gmail messages
curl "http://127.0.0.1:3719/google/gmail/messages?user_id=user-uuid"

# List Calendar events
curl "http://127.0.0.1:3719/google/calendar/events?user_id=user-uuid"

# List Drive files
curl "http://127.0.0.1:3719/google/drive/files?user_id=user-uuid"

# Read a Google Sheet
curl "http://127.0.0.1:3719/google/sheets/SPREADSHEET_ID?user_id=user-uuid"

API Reference

Available APIs

The plugin requests all scopes during the initial OAuth consent. Users see a single permissions screen covering all enabled APIs.

Database Tables

The plugin creates a dedicated np_google schema. These tables are auto-tracked by Hasura and accessible via GraphQL.

# Check which users have connected Google accounts
query ConnectedAccounts {
  np_google_tokens(where: { expires_at: { _gt: "now()" } }) {
    user_id
    scopes
    connected_at
  }
}

# Audit recent API calls
query RecentSync {
  np_google_sync_log(
    order_by: { created_at: desc }
    limit: 20
    where: { status: { _eq: "error" } }
  ) {
    user_id
    api
    operation
    error_message
    created_at
  }
}

Events Emitted

These events are published to the nself event bus and can be consumed by nself-mux rules.

vs SaaS Alternatives

Troubleshooting

OAuth consent screen not appearing

Make sure the OAuth Client ID type is set to Web application (not Desktop or TV). The redirect URI must exactly match https://your-domain.com/google/auth/callback — trailing slashes matter.

Error: invalid_grant after token stored

This means the refresh token was revoked — either by the user in their Google Account settings, or because your OAuth app is in “testing” mode (tokens expire after 7 days). Publish the app in Google Cloud Console to issue permanent tokens.

Scope insufficient errors on Gmail send

If you enabled the Gmail API after the user already authenticated, their stored token won't include gmail.modify scope. Delete the row from np_google.tokens for that user and have them re-authorize via /google/auth/url.

Plugin health check fails

curl http://127.0.0.1:3719/google/health
# Check PLUGIN_GOOGLE_CLIENT_ID and PLUGIN_GOOGLE_CLIENT_SECRET are set
nself config get | grep PLUGIN_GOOGLE

Rate limits from Google APIs

Gmail and Calendar have per-user quotas (250 quota units/second for Gmail). Check np_google.sync_log for status: "error" rows with HTTP 429. Add exponential backoff in your calling code or use nself-cron to spread API calls across time.

Uninstall

nself plugin remove google

Related

• Plugin Overview: Tier table, license setup, lifecycle commands
• nself-cron: Schedule Google API calls on a recurring basis
• nself-mux: Route inbound Gmail messages through processing rules
• nself-notify: Trigger push notifications from Google Calendar events

Port: 3719 | Bundle: ɳClaw ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.1.0