> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Integrations

> Configure Google Calendar, Gmail, Drive, Sheets, Slides, Docs, and Contacts 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

1. Navigate to [Google Cloud Console](https://console.cloud.google.com/)
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**

### Step 2: Configure OAuth Consent Screen

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

<Warning>
  **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.
</Warning>

3. Click **Create**
4. 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
5. 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](#required-scopes-per-integration) 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:

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

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

## 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 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](/features/built-in-integrations-overview#oauth-redirect-uri-patterns) for the correct redirect URI format based on your ingress configuration.

### 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

<Warning>
  The Client Secret is only shown once. If you lose it, you'll need to create a new one.
</Warning>

## 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 |

<Note>
  `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.
</Note>

#### Granting Gmail API Publisher Access

**Option 1: Via gcloud CLI**

```bash theme={null}
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:

```yaml theme={null}
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`
   <Warning>
     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.
   </Warning>
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

| 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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](/reference/chart-values/oauth) 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](/features/built-in-integrations-overview#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:

```yaml theme={null}
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)

<Warning>
  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.
</Warning>