Google Workspace Integrations

Overview

CrewAI supports integration with Google Workspace applications including Calendar, Gmail, Drive, Sheets, Slides, Docs, and Contacts. This guide walks you through setting up OAuth credentials in Google Cloud Console to enable these integrations.

Prerequisites

A Google Cloud account with billing enabled
Access to create projects in Google Cloud Console
Admin access to configure OAuth consent screen

Google Cloud Console Setup

Step 1: Create or Select a Project

Navigate to Google Cloud Console
Click the project dropdown in the top navigation bar
Either select an existing project or click New Project
If creating a new project:
- Enter a project name (e.g., “CrewAI Integrations”)
- Select your organization (if applicable)
- Click Create

In the Google Cloud Console, navigate to APIs & Services > OAuth consent screen
Select the User Type:

Internal vs External Apps

Internal: Only available to users within your Google Workspace organization. Recommended for enterprise deployments as it skips Google’s app verification process.
External: Available to any Google account user. Requires Google’s app verification process which can take several weeks for sensitive scopes.

For faster deployment, select Internal if your CrewAI users are all within the same Google Workspace organization.

Click Create
Fill in the required fields:
- App name: Enter your application name (e.g., “CrewAI”)
- User support email: Select your email address
- App logo: (Optional) Upload your company logo
- App domain: Add your application domain
- Developer contact information: Enter your email address
Click Save and Continue

Step 3: Configure Scopes

On the Scopes page, click Add or Remove Scopes
Add the scopes required for your integrations (see Required Scopes below)
Click Update then Save and Continue

Step 4: Add Test Users (Internal Apps)

If you selected Internal user type, all users in your organization can access the app. If you selected External and the app is in testing mode:

Click Add Users
Enter the email addresses of users who need to test the integration
Click Add then Save and Continue

Enable Required APIs

Enable the APIs for the Google services you want to integrate:

Navigate to APIs & Services > Library
Search for and enable each required API:

Integration	API to Enable
Google Calendar	Google Calendar API
Google Contacts	People API
Gmail	Gmail API
Google Sheets	Google Sheets API
Google Drive	Google Drive API
Google Slides	Google Slides API
Google Docs	Google Docs API

For Google Slides integration, you also need to enable the Google Sheets API and Google Drive API as Slides uses these for certain operations.

Create OAuth 2.0 Credentials

Step 1: Create OAuth Client ID

Navigate to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Select Web application as the application type
Enter a name for the client (e.g., “CrewAI OAuth Client”)

Step 2: Configure Redirect URIs

Add the authorized redirect URI. Default configuration (NGINX with shared hostname):

https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/add

Separate OAuth hostname (GKE/ALB with path: "/"):

https://<YOUR_OAUTH_HOST>/oauth/add

See OAuth Redirect URI Patterns for the correct redirect URI format based on your ingress configuration.

Step 3: Save Credentials

Click Create
A dialog will display your Client ID and Client Secret
Store these securely — you’ll need them for CrewAI configuration

The Client Secret is only shown once. If you lose it, you’ll need to create a new one.

Required Scopes per Integration

The following table lists all OAuth scopes required for each Google integration. These scopes should be added to your OAuth consent screen configuration.

Google Calendar

Scope	Description
`https://www.googleapis.com/auth/calendar.readonly`	View calendar events
`https://www.googleapis.com/auth/calendar`	Full access to calendars
`https://www.googleapis.com/auth/calendar.freebusy`	Check free/busy information

Google Contacts

Scope	Description
`https://www.googleapis.com/auth/contacts.readonly`	Read contacts
`https://www.googleapis.com/auth/contacts`	Full access to contacts
`https://www.googleapis.com/auth/contacts.other.readonly`	Read “Other contacts”
`https://www.googleapis.com/auth/directory.readonly`	Read directory information

Gmail

Scope	Description
`https://www.googleapis.com/auth/gmail.readonly`	Read emails and settings
`https://www.googleapis.com/auth/gmail.send`	Send emails
`https://www.googleapis.com/auth/gmail.modify`	Modify emails (labels, read status)
`https://www.googleapis.com/auth/gmail.compose`	Create and edit drafts

Gmail Triggers

Gmail Triggers enable real-time email notifications. It requires a Google Cloud service account for Pub/Sub management.

Required Google Cloud APIs

API	Purpose
`gmail.googleapis.com`	Gmail API for watch requests
`pubsub.googleapis.com`	Pub/Sub for push notifications
`cloudresourcemanager.googleapis.com`	Resource management

Service Account Requirements

You need to configure two service accounts: 1. Your Service Account (Customer-created) Create a service account in your Google Cloud project with roles/pubsub.admin:

Role	Purpose
`roles/pubsub.admin`	Create/manage Pub/Sub topics and subscriptions

This is the service account whose credentials you provide in oauth.secrets.google.gmail.triggers.serviceAccountCredentials. 2. Gmail API Service Account (Google-managed) Gmail uses its internal service account to publish notifications to your Pub/Sub topic. You must grant it publisher access:

Principal	Role	Resource
`gmail-api-push@system.gserviceaccount.com`	`roles/pubsub.publisher`	Your Pub/Sub topic

gmail-api-push@system.gserviceaccount.com is managed by Google - you won’t see it in your project’s service accounts. You simply grant it access to your topic.

Granting Gmail API Publisher Access

Option 1: Via gcloud CLI

gcloud pubsub topics add-iam-policy-binding gmail-notifications \
  --member="serviceAccount:gmail-api-push@system.gserviceaccount.com" \
  --role="roles/pubsub.publisher" \
  --project=YOUR_PROJECT_ID

Option 2: Via Google Cloud Console

Navigate to Pub/Sub → Topics → Select your topic
Click the Permissions tab
Click Grant Access
In “New principals”, enter: gmail-api-push@system.gserviceaccount.com
Select role: Pub/Sub Publisher
Click Save

If you encounter this error:

“The ‘Domain Restricted Sharing’ organization policy (constraints/iam.allowedPolicyMemberDomains) is enforced.”

Your organization blocks external service accounts. Contact your GCP administrator to add system.gserviceaccount.com to the allowed domains:

constraint: constraints/iam.allowedPolicyMemberDomains
listPolicy:
  allowedValues:
    - 'your-company.com'
    - 'system.gserviceaccount.com'  # Required for Gmail API

Setup Steps

Enable required APIs in Google Cloud Console
Create a service account with roles/pubsub.admin
Create a Pub/Sub topic named gmail-notifications
When creating the topic, uncheck “Add a default subscription”. Google enables this by default, but CrewAI creates its own subscriptions dynamically. The default subscription is unnecessary and will accumulate unprocessed messages.
Grant gmail-api-push@system.gserviceaccount.com publisher access to the topic (see above)
Download your service account JSON key
Configure in helm values under oauth.secrets.google.gmail.triggers.serviceAccountCredentials

Google Sheets

Scope	Description
`https://www.googleapis.com/auth/spreadsheets.readonly`	Read spreadsheets
`https://www.googleapis.com/auth/spreadsheets`	Full access to spreadsheets

Google Drive

Scope	Description
`https://www.googleapis.com/auth/drive.file`	Access files created by or opened with the app

Google Slides

Scope	Description
`https://www.googleapis.com/auth/presentations`	Full access to presentations
`https://www.googleapis.com/auth/presentations.readonly`	Read presentations
`https://www.googleapis.com/auth/spreadsheets`	Access spreadsheets (for chart data)
`https://www.googleapis.com/auth/drive.file`	Access Drive files

Google Docs

Scope	Description
`https://www.googleapis.com/auth/documents.readonly`	Read documents
`https://www.googleapis.com/auth/documents`	Full access to documents

Configure CrewAI Helm Values

After obtaining your OAuth credentials, configure them in your CrewAI Helm values:

oauth:
  enabled: true
  secrets:
    google:
      clientId: "your-client-id.apps.googleusercontent.com"
      clientSecret: "your-client-secret"

You can also configure product-specific credentials if you need separate OAuth apps for different Google services:

oauth:
  secrets:
    google:
      # Shared credentials (used as fallback)
      clientId: "shared-client-id.apps.googleusercontent.com"
      clientSecret: "shared-client-secret"

      # Product-specific overrides (optional)
      gmail:
        clientId: "gmail-specific-client-id.apps.googleusercontent.com"
        clientSecret: "gmail-specific-client-secret"
      calendar:
        clientId: "calendar-specific-client-id.apps.googleusercontent.com"
        clientSecret: "calendar-specific-client-secret"

For Google Drive file picker functionality, you also need an API key:

oauth:
  secrets:
    google:
      clientId: "your-client-id.apps.googleusercontent.com"
      clientSecret: "your-client-secret"
      drivePickerKey: "your-api-key"

To create an API key:

Navigate to APIs & Services > Credentials
Click Create Credentials > API Key
Restrict the key to the Google Picker API for security

See Built-in Integrations Configuration for complete configuration options.

Activate the Integration

After deploying your updated Helm values, sync integrations to make them available to users — see Activate Integrations After Deployment.

Support Google Workspace Identity

To restrict users to connecting to Built-In Integrations from a specific Google Workspace domain only (preventing personal Gmail accounts from authenticating), configure the googleWorkspaceDomain setting:

oauth:
  enabled: true
  config:
    googleWorkspaceDomain: "company.com"
  secrets:
    google:
      clientId: "your-client-id.apps.googleusercontent.com"
      clientSecret: "your-client-secret"

When configured:

Only users with email addresses from the specified domain (e.g., @company.com) can authenticate
Personal Gmail accounts (@gmail.com) will be rejected
This applies to all Google integrations (Calendar, Gmail, Drive, Sheets, Slides, Docs, and Contacts)

This setting requires your Google Cloud OAuth consent screen to be configured as Internal user type, which automatically restricts to your Google Workspace organization. If using External user type, this domain restriction provides an additional layer of filtering.

Core Configuration

Authentication

Built-In Integrations

Advanced

Overview

Prerequisites

Google Cloud Console Setup

Step 1: Create or Select a Project

Step 3: Configure Scopes

Step 4: Add Test Users (Internal Apps)

Enable Required APIs

Create OAuth 2.0 Credentials

Step 1: Create OAuth Client ID

Step 2: Configure Redirect URIs

Step 3: Save Credentials

Required Scopes per Integration

Google Calendar

Google Contacts

Gmail

Gmail Triggers

Required Google Cloud APIs

Service Account Requirements

Granting Gmail API Publisher Access

Setup Steps

Google Sheets

Google Drive

Google Slides

Google Docs

Configure CrewAI Helm Values

Activate the Integration

Support Google Workspace Identity

​Overview

​Prerequisites

​Google Cloud Console Setup

​Step 1: Create or Select a Project

​Step 2: Configure OAuth Consent Screen

​Step 3: Configure Scopes

​Step 4: Add Test Users (Internal Apps)

​Enable Required APIs

​Create OAuth 2.0 Credentials

​Step 1: Create OAuth Client ID

​Step 2: Configure Redirect URIs

​Step 3: Save Credentials

​Required Scopes per Integration

​Google Calendar

​Google Contacts

​Gmail

​Gmail Triggers

​Required Google Cloud APIs

​Service Account Requirements

​Granting Gmail API Publisher Access

​Domain Restricted Sharing Policy

​Setup Steps

​Google Sheets

​Google Drive

​Google Slides

​Google Docs

​Configure CrewAI Helm Values

​Activate the Integration

​Support Google Workspace Identity

Overview

Prerequisites

Google Cloud Console Setup

Step 1: Create or Select a Project

Step 2: Configure OAuth Consent Screen

Step 3: Configure Scopes

Step 4: Add Test Users (Internal Apps)

Enable Required APIs

Create OAuth 2.0 Credentials

Step 1: Create OAuth Client ID

Step 2: Configure Redirect URIs

Step 3: Save Credentials

Required Scopes per Integration

Google Calendar

Google Contacts

Gmail

Gmail Triggers

Required Google Cloud APIs

Service Account Requirements

Granting Gmail API Publisher Access

Domain Restricted Sharing Policy

Setup Steps

Google Sheets

Google Drive

Google Slides

Google Docs

Configure CrewAI Helm Values

Activate the Integration

Support Google Workspace Identity