Connect Google Sheets, Docs, and Drive using a service account.

Overview

A service account is a dedicated email address created for your team. You share Google resources with this email to grant your agents access.

Best for:

• Team shared spreadsheets
• Company Drive folders
• Public or shared Google resources

How it works

11. Connect → We create a service account email22. Share → You share your Google Sheet/Doc/Drive with that email33. Access → Your agents can read/write the shared resources

No OAuth consent screens, no personal account linking — just simple file sharing.

Connecting

1. Go to Settings → Secrets → Integrations
2. Find Google Service Account and click Connect
3. Copy the generated email (e.g., [email protected])

That's it — the service account is ready to use.

Sharing resources

Google Sheets

1. Open your Google Sheet
2. Click Share (top right)
3. Paste the service account email
4. Choose permission:
   • Viewer — read-only access
   • Editor — read and write access
5. Click Send (uncheck "Notify people" if you want)

Google Docs

Same process as Sheets:

1. Open your Google Doc
2. Click Share
3. Paste the service account email
4. Set permissions and share

Google Drive folders

Share an entire folder to give access to all files within:

1. Right-click the folder in Drive
2. Select Share
3. Paste the service account email
4. Set permissions

All files in the folder will be accessible.

Capabilities

Service accounts access whatever you've shared with them — no additional scope configuration needed.

Security

The service account can only access files explicitly shared with it. It cannot browse your Drive or access anything you haven't shared.

Using in apps

Declare the requirement in your app:

1integrations:2    - key: google.sa3        description: Access team spreadsheets

At runtime, your app receives:

1GOOGLE_ACCESS_TOKEN=ya29...2GOOGLE_SERVICE_ACCOUNT_EMAIL=agent-yourteam@...3GOOGLE_TOKEN_EXPIRES_IN=3600

Example: Read a Google Sheet

1import gspread2from google.oauth2.credentials import Credentials3 4creds = Credentials(token=os.environ["GOOGLE_ACCESS_TOKEN"])5client = gspread.authorize(creds)6 7# Open by URL (must be shared with the service account)8sheet = client.open_by_url("https://docs.google.com/spreadsheets/d/...")9data = sheet.sheet1.get_all_records()

Troubleshooting

"Permission denied" on a shared resource

• Verify the service account email is in the resource's sharing settings
• Check the permission level (Viewer vs Editor)
• For Drive, make sure the file isn't restricted to organization members only

"File not found"

• Double-check the file/sheet URL or ID
• Confirm the file is shared with the service account email
• Organization files may have sharing restrictions — check with your admin

Service account email not showing

• Go to Settings → Integrations and look for the connected Google Service Account
• The email is displayed in the integration card

Service Account vs OAuth

Use Service Account for team resources. Use Google OAuth for personal services like Gmail and Calendar.

Next

→ Google OAuth