Skip to main content

​
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

  1. Navigate to Google Cloud Console
  2. Click the project dropdown in the top navigation bar
  3. Either select an existing project or click New Project
  4. If creating a new project:
    • Enter a project name (e.g., “CrewAI Integrations”)
    • Select your organization (if applicable)
    • Click Create
  1. In the Google Cloud Console, navigate to APIs & Services > OAuth consent screen
  2. 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.
  1. Click Create
  2. 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
  3. Click Save and Continue

​
Step 3: Configure Scopes

  1. On the Scopes page, click Add or Remove Scopes
  2. Add the scopes required for your integrations (see Required Scopes below)
  3. 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:
  1. Click Add Users
  2. Enter the email addresses of users who need to test the integration
  3. Click Add then Save and Continue

​
Enable Required APIs

Enable the APIs for the Google services you want to integrate:
  1. Navigate to APIs & Services > Library
  2. Search for and enable each required API:
IntegrationAPI to Enable
Google CalendarGoogle Calendar API
Google ContactsPeople API
GmailGmail API
Google SheetsGoogle Sheets API
Google DriveGoogle Drive API
Google SlidesGoogle Slides API
Google DocsGoogle 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

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

​
Step 2: Configure Redirect URIs

Add the authorized redirect URIs for each Google integration you want to enable. Default configuration (NGINX with shared hostname): 
https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/google_calendar/callback
https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/google_contacts/callback
https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/google_gmail/callback
https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/google_sheets/callback
https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/google_drive/callback
https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/google_slides/callback
https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/google_docs/callback
Separate OAuth hostname (GKE/ALB with path: "/"): 
https://<YOUR_OAUTH_HOST>/oauth/google_calendar/callback
https://<YOUR_OAUTH_HOST>/oauth/google_contacts/callback
https://<YOUR_OAUTH_HOST>/oauth/google_gmail/callback
https://<YOUR_OAUTH_HOST>/oauth/google_sheets/callback
https://<YOUR_OAUTH_HOST>/oauth/google_drive/callback
https://<YOUR_OAUTH_HOST>/oauth/google_slides/callback
https://<YOUR_OAUTH_HOST>/oauth/google_docs/callback
When using GKE’s native ingress or a separate OAuth hostname with oauth.ingress.path: "/", the /oauthsvc prefix is not included in the callback URLs. See OAuth Ingress Path Configuration for details.

​
Step 3: Save Credentials

  1. Click Create
  2. A dialog will display your Client ID and Client Secret
  3. 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

ScopeDescription
https://www.googleapis.com/auth/calendar.readonlyView calendar events
https://www.googleapis.com/auth/calendarFull access to calendars
https://www.googleapis.com/auth/calendar.freebusyCheck free/busy information

​
Google Contacts

ScopeDescription
https://www.googleapis.com/auth/contacts.readonlyRead contacts
https://www.googleapis.com/auth/contactsFull access to contacts
https://www.googleapis.com/auth/contacts.other.readonlyRead “Other contacts”
https://www.googleapis.com/auth/directory.readonlyRead directory information

​
Gmail

ScopeDescription
https://www.googleapis.com/auth/gmail.readonlyRead emails and settings
https://www.googleapis.com/auth/gmail.sendSend emails
https://www.googleapis.com/auth/gmail.modifyModify emails (labels, read status)
https://www.googleapis.com/auth/gmail.composeCreate 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

APIPurpose
gmail.googleapis.comGmail API for watch requests
pubsub.googleapis.comPub/Sub for push notifications
cloudresourcemanager.googleapis.comResource 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:
RolePurpose
roles/pubsub.adminCreate/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:
PrincipalRoleResource
gmail-api-push@system.gserviceaccount.comroles/pubsub.publisherYour 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
  1. Navigate to Pub/Sub → Topics → Select your topic
  2. Click the Permissions tab
  3. Click Grant Access
  4. In “New principals”, enter: gmail-api-push@system.gserviceaccount.com
  5. Select role: Pub/Sub Publisher
  6. Click Save

​
Domain Restricted Sharing Policy

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

  1. Enable required APIs in Google Cloud Console
  2. Create a service account with roles/pubsub.admin
  3. 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.
  4. Grant gmail-api-push@system.gserviceaccount.com publisher access to the topic (see above)
  5. Download your service account JSON key
  6. Configure in helm values under oauth.secrets.google.gmail.triggers.serviceAccountCredentials

​
Google Sheets

ScopeDescription
https://www.googleapis.com/auth/spreadsheets.readonlyRead spreadsheets
https://www.googleapis.com/auth/spreadsheetsFull access to spreadsheets

​
Google Drive

ScopeDescription
https://www.googleapis.com/auth/drive.fileAccess files created by or opened with the app

​
Google Slides

ScopeDescription
https://www.googleapis.com/auth/presentationsFull access to presentations
https://www.googleapis.com/auth/presentations.readonlyRead presentations
https://www.googleapis.com/auth/spreadsheetsAccess spreadsheets (for chart data)
https://www.googleapis.com/auth/drive.fileAccess Drive files

​
Google Docs

ScopeDescription
https://www.googleapis.com/auth/documents.readonlyRead documents
https://www.googleapis.com/auth/documentsFull 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:
  1. Navigate to APIs & Services > Credentials
  2. Click Create Credentials > API Key
  3. Restrict the key to the Google Picker API for security
See Built-in Integrations Configuration for complete configuration options.

​
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.