Google Workspace Connector

Connect DatumOS to your Google Workspace or personal Google account to search Google Drive files, Gmail messages, and access Google Calendar events directly from AI conversations.

Overview

The Google Workspace connector integrates with Google APIs to provide access to:

• Google Drive - Search personal and shared files, including Team Drives
• Gmail - Search emails with Gmail’s powerful query operators
• Google Calendar - View calendar events and availability

Prerequisites

Before connecting Google Workspace, ensure you have:

• Google Account - Personal Gmail account or Google Workspace account
• Active Services - Access to Drive, Gmail, and/or Calendar
• Browser Access - Modern web browser with cookies enabled for OAuth
• Workspace Admin Approval (Business accounts) - May require IT administrator consent for certain permissions

Connecting Your Google Account

Step 1: Navigate to Settings

1. Click your profile icon in the top-right corner
2. Select Settings from the dropdown menu
3. Go to the Connectors tab

Step 2: Initiate Connection

1. Find Google Workspace in the connector list
2. Click the Connect button
3. You’ll be redirected to Google’s authorization page

Step 3: Sign In and Authorize

1. Choose your Google account (or sign in if not already logged in)
2. Review the requested permissions (see Permissions and Scopes)
3. If using a Google Workspace account, you may see a verification required notice
4. Click Allow to grant DatumOS access to your Google data
5. You’ll be redirected back to DatumOS Settings

Step 4: Verify Connection

Once connected, the Google Workspace connector will show a Connected status with a green indicator. You can now use Google data in your conversations.

Workspace Admin Consent (Business Accounts)

If you’re using a Google Workspace account, certain operations may require administrator approval:

When Admin Approval is Required

• Domain-wide delegation - Access to other users’ data
• Shared Drive access - Reading Team Drives in your organization
• Advanced Gmail scopes - Sending emails or modifying messages (coming soon)

How to Request Admin Approval

1. During the OAuth flow, you may see a Verification required notice
2. Contact your Google Workspace administrator
3. Provide them with DatumOS OAuth client information
4. Once approved, reconnect the Google Workspace connector

For Google Workspace Administrators

Administrators can manage third-party app access:

1. Go to Google Admin Console 
2. Navigate to Security → Access and data control → API controls
3. Find DatumOS in the connected apps list
4. Review and approve requested OAuth scopes

Supported Services

Google Drive

Search files stored in Google Drive, including My Drive, Shared with Me, and Team Drives:

Supported File Types:

• Google Docs, Sheets, and Slides
• Microsoft Office files (Word, Excel, PowerPoint)
• PDF documents
• Images and photos
• Text files and code
• Any file type stored in Drive

Search Capabilities:

• Full-text search across file names and content
• Filter by file type (MIME type)
• Filter by creation or modification date
• Search files shared by specific users
• Access recently modified files

Example Questions:

• “Find the project proposal document in my Google Drive”
• “Search for spreadsheets updated this week”
• “Show me PDFs shared by the design team”
• “What presentations did I create last month?”

Performance:

• Sub-3-second response times for most searches
• Results cached for 5 minutes to improve performance
• Automatic retry with exponential backoff on errors

Gmail

Search and retrieve emails from your Gmail inbox:

Search Capabilities:

• Full-text search across subject, body, and sender
• Gmail query operators (e.g., from:, subject:, has:attachment)
• Filter by label, date range, or importance
• Search by starred, read/unread status
• Access email snippets and metadata

Supported Query Operators:

• from:user@example.com - Emails from specific sender
• to:user@example.com - Emails to specific recipient
• subject:"project update" - Subject contains phrase
• has:attachment - Emails with attachments
• is:unread - Unread messages only
• after:2024/12/01 - Emails after specific date
• label:important - Emails with specific label

Example Questions:

• “Find emails from Sarah about the budget”
• “Show me unread messages with attachments from this week”
• “Search for emails labeled ‘Project X’ from last month”
• “What emails did I receive from john@example.com yesterday?”

Performance:

• Sub-3-second response times for most searches
• Results cached for 5 minutes
• Supports pagination for large result sets

Google Calendar

View calendar events and check availability:

Capabilities:

• Search Events - Find meetings by title, attendee, or date range
• View Details - See event time, location, attendees, and description
• All-Day Events - Filter for all-day events
• Timezone Support - Handle multiple timezones

Example Questions:

• “What meetings do I have today?”
• “Show me calendar events next week with John”
• “Do I have any all-day events this month?”
• “What’s on my schedule for Friday afternoon?”

Performance:

• Sub-3-second response times
• Results cached for 5 minutes
• Supports multiple calendars if authorized

Permissions and Scopes

The Google Workspace connector requests the following OAuth scopes:

Current Limitations

The Google Workspace connector is currently read-only. The following capabilities are planned for future releases:

Coming Soon:

• Gmail Write - Send emails and create drafts
• Calendar Write - Create and modify calendar events with Google Meet links
• Drive Write - Upload files and create folders

See the Roadmap for planned features and timelines.

Sync Frequency

The Google Workspace connector operates in real-time mode:

• No Background Sync - Data is fetched only when you ask questions
• Always Current - Every search retrieves the latest data from Google
• Temporary Caching - Search results cached for 5 minutes to improve performance
• No Content Storage - DatumOS does not permanently store email or file contents
• Live Connection - Requires active internet connection

Connection Status

Monitor your Google Workspace connector status in Settings → Connectors:

• Connected (Green) - Authentication valid, ready to use
• Expired (Yellow) - OAuth token expired, click Reconnect
• Error (Red) - Connection failed, check credentials or network

Token Expiration

OAuth tokens for Google Workspace automatically refresh using offline_access. However, if unused for 6 months, tokens may be revoked by Google. When your token expires:

1. Go to Settings → Connectors
2. Click Reconnect next to Google Workspace
3. Complete the OAuth flow again
4. Resume using Google data immediately

Rate Limits

Google APIs enforce rate limits per user and per project:

• Drive API - 1,000 requests per 100 seconds per user
• Gmail API - 250 quota units per user per second
• Calendar API - 1,000,000 queries per day (shared across all users)

If you encounter rate limiting:

• DatumOS automatically retries with exponential backoff
• Cached results are served when available
• Wait 1-2 minutes before retrying manually if errors persist

Sync Options

Personal vs. Workspace Accounts

Personal Gmail Accounts:

• Access your own Drive, Gmail, and Calendar
• No admin approval required
• Limited to your personal data

Google Workspace Accounts:

• Access your own data plus shared Team Drives (if authorized)
• May require IT administrator approval
• Enhanced security and compliance features

Data Scope

DatumOS accesses only the data you explicitly authorize:

• My Drive - Your personal Drive files
• Shared with Me - Files others have shared with you
• Team Drives - Organization shared drives (if Workspace admin approves)
• Gmail - Your personal mailbox only
• Calendar - Your primary calendar (additional calendars require separate authorization)

Troubleshooting

Common Issues

Drive Access Issues

If you can’t find files you know exist:

1. Check Permissions - Verify you have access in Google Drive web interface
2. Refresh Connection - Disconnect and reconnect to refresh permissions
3. Team Drive Access - Ensure your Workspace admin has authorized Team Drive access
4. File Type - Some Google Apps Script files may not be searchable
5. Indexing Delay - New files may take 1-2 minutes to appear in search results

Gmail Issues

If emails aren’t showing in search results:

1. Query Syntax - Verify Gmail query operators are correct
2. Label Names - Use exact label names (case-sensitive)
3. Date Format - Use YYYY/MM/DD format for date queries
4. Scope Authorization - Ensure Gmail.readonly scope is authorized
5. Spam/Trash - Emails in Spam or Trash are excluded from searches

Calendar Issues

If calendar events aren’t showing:

1. Calendar Access - Verify you’ve authorized access to your primary calendar
2. Time Range - Ensure date range includes the events you’re searching for
3. Timezone - Check your browser timezone matches expected results
4. Multiple Calendars - Only primary calendar is accessible by default
5. Shared Calendars - Additional authorization required for shared calendars

Workspace Admin Issues

If your Google Workspace administrator needs to approve access:

1. Contact IT - Reach out to your Google Workspace administrator
2. Application Info - Provide DatumOS OAuth client information
3. Scope List - Share the Permissions and Scopes table
4. Security Review - Direct admins to DatumOS security documentation
5. Admin Console - Admins can review connected apps at admin.google.com

Security & Compliance

Data Privacy

• No Content Storage - DatumOS does not permanently store email or file contents
• Temporary Caching - Search results cached for 5 minutes only
• User Isolation - You can only access data you have permission to view
• Token Security - OAuth tokens are encrypted at rest and in transit
• Revocation Support - Disconnect at any time to revoke access

Audit Logging

All Google Workspace connector operations are logged for compliance:

• User ID and timestamp
• Operation type (search, retrieve)
• Resource IDs accessed (file IDs, email IDs, event IDs)
• Response times and result counts
• Success/error status

Logs are retained for 90 days and available to account administrators.

Compliance Certifications

DatumOS follows Google’s security best practices:

• OAuth 2.0 - Industry-standard authentication
• Least Privilege - Requests only required permissions (read-only)
• Token Refresh - Automatic token rotation with refresh tokens
• Secure Storage - Encrypted token storage
• GDPR Compliance - Data handling complies with European privacy regulations

Next Steps

Further Reading

• Google Drive API Documentation 
• Gmail API Documentation 
• Google Calendar API Documentation 
• Google Workspace Admin Console 
• OAuth 2.0 Scopes Reference