> ## Documentation Index
> Fetch the complete documentation index at: https://sofiedocs.usetransfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace integration

> Set up Sofie access to Gmail, Google Calendar, and Google Drive through a Google Cloud OAuth client.

The Google Workspace integration lets Sofie use Gmail, Google Calendar, and Google Drive when your organization enables the provider and a user connects their account.

Use this guide if you administer Google Cloud or Google Workspace apps for your organization.

## What Sofie can use

Depending on permissions and user consent, Sofie may use Google Workspace to:

* Search and read Gmail messages.
* Draft and send Gmail messages after review.
* Read Google Calendar events.
* Create calendar events after review.
* Search Google Drive files.
* Import useful Drive files into a Workspace.

## Before you start

You need:

* Access to the Google Cloud project used for Sofie OAuth.
* Permission to configure the OAuth consent screen.
* Permission to create OAuth client credentials.
* The Sofie domain users open in the browser.
* Access to Sofie **Organization Settings** > **Integrations**.

## Redirect URI

Add this authorized redirect URI to the Google OAuth client:

```text theme={null}
https://<your-sofie-domain>/api/integrations/callback/google
```

Use the exact Sofie domain for the environment. Add staging and production redirect URIs separately when needed.

## Configure the OAuth consent screen

<Steps>
  <Step title="Open Google Cloud Console">
    Open the Google Cloud project that should own the Sofie OAuth app.
  </Step>

  <Step title="Open OAuth consent">
    Go to **APIs & Services** and open the OAuth consent or branding area shown by your Google Cloud Console.
  </Step>

  <Step title="Choose user type">
    Choose the user type your organization requires. Internal apps are typically limited to your Google Workspace organization.
  </Step>

  <Step title="Add application details">
    Add the app name, support email, authorized domains, and contact information.
  </Step>

  <Step title="Add scopes">
    Add only the Gmail, Calendar, Drive, and profile scopes your organization wants Sofie to use.
  </Step>

  <Step title="Add test users if needed">
    If the app is still in testing, add test users before asking them to connect.
  </Step>
</Steps>

Google reference: [OAuth 2.0 for web server applications](https://developers.google.com/identity/protocols/oauth2/web-server).

## Create the OAuth client

<Steps>
  <Step title="Open Credentials">
    In Google Cloud Console, go to **APIs & Services** > **Credentials**.
  </Step>

  <Step title="Create OAuth client ID">
    Choose **Create credentials** > **OAuth client ID**.
  </Step>

  <Step title="Choose Web application">
    Select **Web application** as the application type.
  </Step>

  <Step title="Add redirect URI">
    Add `https://<your-sofie-domain>/api/integrations/callback/google` under authorized redirect URIs.
  </Step>

  <Step title="Copy credentials">
    Copy the client ID and client secret.
  </Step>
</Steps>

## Enable Google APIs

Enable the APIs that match the Sofie capabilities you want to support:

* Gmail API.
* Google Calendar API.
* Google Drive API.

Google API references:

* [Gmail API authorization scopes](https://developers.google.com/gmail/api/auth/scopes)
* [Google Calendar API authorization](https://developers.google.com/workspace/calendar/api/auth)
* [Google Drive API authorization](https://developers.google.com/drive/api/guides/api-specific-auth)

## Configure scopes

Sofie may request scopes for the capabilities your organization enables.

| Capability            | Google scope examples                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| Gmail read and search | `https://www.googleapis.com/auth/gmail.readonly`                                                     |
| Gmail send            | `https://www.googleapis.com/auth/gmail.send`                                                         |
| Calendar read         | `https://www.googleapis.com/auth/calendar.readonly`                                                  |
| Calendar event write  | `https://www.googleapis.com/auth/calendar.events`                                                    |
| Drive file read       | `https://www.googleapis.com/auth/drive.readonly`                                                     |
| Drive metadata        | `https://www.googleapis.com/auth/drive.metadata.readonly`                                            |
| User profile          | `https://www.googleapis.com/auth/userinfo.email`, `https://www.googleapis.com/auth/userinfo.profile` |

<Warning>
  Some Google scopes may require additional review or verification by Google depending on your app configuration and audience. Confirm requirements in Google Cloud before rolling out broadly.
</Warning>

## Add values in Sofie

In Sofie, go to **Organization Settings** > **Integrations** and open Google.

Enter:

| Sofie field       | Google value         |
| ----------------- | -------------------- |
| **Client ID**     | OAuth client ID.     |
| **Client Secret** | OAuth client secret. |

Enable Google and save settings.

## Test the connection

<Steps>
  <Step title="Connect a test user">
    Use a Google Workspace account with representative access.
  </Step>

  <Step title="Review the consent screen">
    Confirm the requested scopes match the capabilities you expect.
  </Step>

  <Step title="Test Gmail">
    Ask Sofie to search a known test email thread.
  </Step>

  <Step title="Test Calendar">
    Ask Sofie to find or draft a test event.
  </Step>

  <Step title="Test Drive">
    Ask Sofie to find a known Drive file and recommend whether it should be imported into a Workspace.
  </Step>
</Steps>

## User prompt examples

```text theme={null}
Search Google Drive for protocol drafts that mention media fill acceptance criteria. Do not import anything yet. Return file name, date, likely relevance, and question to confirm.
```

```text theme={null}
Find Google Calendar meetings next week with the validation team and draft a proposed agenda. Do not create an event yet.
```

```text theme={null}
Search Gmail for recent messages about release assay readiness. Summarize open questions and list sender, date, and thread title.
```

## Troubleshooting

<Accordion title="Users cannot connect Google">
  Confirm Google is enabled in Sofie, the OAuth client is a web application, the redirect URI matches exactly, and the user is allowed by the consent screen configuration.
</Accordion>

<Accordion title="The app says access is blocked">
  Check the OAuth consent screen status, test user list, authorized domains, and whether Google requires verification for the requested scopes.
</Accordion>

<Accordion title="Drive files do not appear">
  Confirm the user can access the file directly in Google Drive and that the integration includes Drive read or metadata scopes.
</Accordion>

<Accordion title="Gmail or Calendar actions are missing">
  Confirm the matching Gmail or Calendar API is enabled and the requested scope is included in the OAuth app configuration.
</Accordion>

## Official Google references

* [OAuth 2.0 for web server applications](https://developers.google.com/identity/protocols/oauth2/web-server)
* [OAuth 2.0 policies](https://developers.google.com/identity/protocols/oauth2/policies)
* [Gmail API authorization scopes](https://developers.google.com/gmail/api/auth/scopes)
* [Google Calendar API authorization](https://developers.google.com/workspace/calendar/api/auth)
* [Google Drive API authorization](https://developers.google.com/drive/api/guides/api-specific-auth)