Google OAuth

Connect your personal Google account for Gmail, Calendar, and Drive.

Overview

Google OAuth connects your personal Google account. Sign in and choose which permissions to grant your agents.

Best for:

• Personal Gmail inbox
• Your calendar
• Personal Drive files
• Sending emails as yourself
• Search Console and Google Analytics reporting (read-only)

How it works

11. Click Connect → Redirect to Google sign-in22. Review scopes → Choose what to allow33. Approve → Tokens are encrypted and stored44. Done → Your agents can access the approved services

Connecting

1. Go to vaults, open the default vault's credentials tab, or open Google Account directly
2. Click Connect
3. Sign in with your Google account
4. Review the requested permissions
5. Click Allow

You'll be redirected back to the credential detail page with your connection active.

Adding permissions

Already connected but need more access? Add permissions incrementally:

1. Open your connected Google OAuth credential
2. Click Add Permissions
3. Select the capabilities you need (e.g., Gmail, Calendar)
4. You'll be redirected to Google to approve the new scopes (Google pre-selects the account you originally connected)
5. Return to inference shell with updated permissions

This uses Google's incremental authorization — your existing permissions are preserved.

Which scopes the platform's client can request

Google connects go through an OAuth client: your workspace's own, if an admin set one up, else the platform's. The platform's Google client is verified by Google for a fixed list of scopes, and inference shell holds it to that list (allowed_scopes on the client): a connect or Add Permissions that asks for a scope outside it is refused before you are sent to Google, with:

1scope https://www.googleapis.com/auth/youtube.readonly is not approved for the platform's Google client; connect through your own OAuth app or ask an admin

Two ways past it:

• Your own OAuth client. A workspace admin registers a Google OAuth client in the Google Cloud console and saves its client id and secret on Google Account (OAuth app), or with PUT /credentials/google/app. Logins from that workspace then go through your client, which has no list and may request any scope your Google project allows (Google shows the unverified-app screen for scopes your project is not verified for).
• Ask an admin. Platform admins edit the platform client's list in the admin console (the company's platform OAuth app → allowed scopes) or as data (PUT /admin/credentials/google with allowed_scopes); a scope is added once Google has approved it for the platform's project.

An app whose inf.yml asks for a scope outside the platform client's list deploys with a warning (unapproved_platform_scope), so the author learns at belt app deploy; the connect is where it is refused.

Available capabilities

Connect and Add Permissions request only the OAuth scope of the capability a tool declares. A login that already holds a broader capability satisfies the narrower one: google.calendar covers google.calendar.events.readonly, and google.gmail.modify covers google.gmail.labels.

Gmail

Calendar

Drive

Apps that only create uploads or folders should declare google.drive.file, so users are not asked for full Drive access.

Sheets & Docs

Search Console & Analytics

Security

Revoking access

You can revoke access two ways:

1. From inference shell: vaults → credentials → disconnect
2. From Google: myaccount.google.com/permissions

Using in apps

Declare OAuth requirements in your app:

1# inf.yml2credentials:3  - key: google.gmail.send4    description: Send order confirmations56  - key: google.calendar.readonly7    description: Check your availability8    optional: true

At runtime, your app receives:

1GOOGLE_OAUTH_ACCESS_TOKEN=ya29...2GOOGLE_OAUTH_TOKEN_EXPIRES_AT=2024-01-15T10:30:00Z

Example: Send an email

1import base642from email.mime.text import MIMEText3from googleapiclient.discovery import build4from google.oauth2.credentials import Credentials56creds = Credentials(token=os.environ["GOOGLE_OAUTH_ACCESS_TOKEN"])7service = build('gmail', 'v1', credentials=creds)89message = MIMEText("Hello from my agent!")10message['to'] = "[email protected]"11message['subject'] = "Automated message"1213raw = base64.urlsafe_b64encode(message.as_bytes()).decode()14service.users().messages().send(15    userId='me',16    body={'raw': raw}17).execute()

Example: List calendar events

1from googleapiclient.discovery import build2from google.oauth2.credentials import Credentials34creds = Credentials(token=os.environ["GOOGLE_OAUTH_ACCESS_TOKEN"])5service = build('calendar', 'v3', credentials=creds)67events = service.events().list(8    calendarId='primary',9    maxResults=10,10    singleEvents=True,11    orderBy='startTime'12).execute()1314for event in events.get('items', []):15    print(event['summary'], event['start'])

Troubleshooting

"Token expired" or "Invalid credentials"

• We auto-refresh tokens, but if the refresh token is revoked, you'll need to reconnect
• Open Google Account — the detail page shows an expired or error banner with the server message and a Reconnect button

"Insufficient permission"

• The requested scope isn't granted
• Use Add Permissions to request the missing capability
• Apps will prompt you if they need scopes you haven't granted

"scope … is not approved for the platform's Google client"

• The connect asked for a scope the platform's verified Google client may not request
• Connect through your workspace's own OAuth client, or ask a platform admin to approve the scope — see Which scopes the platform's client can request

"Access blocked: This app's request is invalid"

• This usually means the OAuth configuration has an issue
• Contact support if this persists

Gmail not working but other services are

• Gmail needs the google.gmail.readonly or google.gmail.send capability, which grants Google's https://www.googleapis.com/auth/gmail.readonly or https://www.googleapis.com/auth/gmail.send scope
• Check that you've granted the Gmail-specific permissions

OAuth vs Service Account

Use OAuth for personal services. Use Service Account for shared resources.

Next

→ Slack