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

# Google Workspace

> Connect Circuit to Google Workspace so agents can read Gmail, prepare Gmail drafts, and read Calendar and Contacts on your behalf.

The Google Workspace integration is a single OAuth grant that lets agents read your Gmail mailbox, prepare Gmail drafts, view your Google Calendar, and look up your Google Contacts. Calendar and Contacts are read-only. Circuit creates Gmail drafts only. It never sends mail.

## What you can do

* **Gmail**: list, search (Gmail query syntax such as `from:alice newer_than:7d has:attachment`), and read messages; create new drafts and reply drafts in your Drafts folder.
* **Calendar**: list your calendars, list and read events in a time window, and run free/busy queries across one or more calendars.
* **Contacts**: list and free-text search the contacts associated with the connected Google account.

Circuit never sends mail, creates calendar events, modifies events, or writes contacts. Every outbound email lands in your Gmail Drafts folder for you to review and send from Gmail yourself.

## Before you start

* A Google Workspace or consumer Google account.
* For Google Workspace tenants with restricted third-party app access, your Workspace administrator may need to mark Circuit as **Trusted** or **Limited** before you can connect. Gmail's read-only scope is classified by Google as a **restricted** scope, which means admins in restricted tenants must approve it explicitly. See [For IT and security teams](#for-it-and-security-teams) below.

## Connect Google Workspace

<Steps>
  <Step title="Open the Google Workspace integration in Circuit">
    In Circuit, open **Settings** > **Integrations** and choose **Google Workspace**.
  </Step>

  <Step title="Sign in with Google">
    Click **Connect Google Workspace**. Google opens its sign-in page in a new window. Sign in with the Google account whose Gmail, Calendar, and Contacts you want Circuit to use.
  </Step>

  <Step title="Review and consent to the requested scopes">
    Google shows a consent screen listing each scope Circuit requests. Review them (see [What Circuit accesses](#what-circuit-accesses) below) and click **Allow**.

    If your Workspace administrator has restricted the integration, you will see "Access blocked: Circuit has not completed the Google verification process" or "your admin has not approved this app." Forward the screen to your Workspace administrator.
  </Step>

  <Step title="Return to Circuit">
    Google redirects you back to Circuit. The integration status changes to **Connected**. Agents that include the Google Workspace tool can now reach Gmail, Calendar, and Contacts under your account.
  </Step>
</Steps>

## What Circuit accesses

Circuit requests the following Google OAuth scopes:

```
openid
email
profile
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/contacts.readonly
```

| Scope                        | Why Circuit needs it                                                                                                                                                                                 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openid`, `email`, `profile` | Standard OpenID Connect scopes. Circuit uses these to identify and label your connected account.                                                                                                     |
| `gmail.readonly`             | View your Gmail messages and settings. Required for listing, searching, and reading mail. This is a **restricted** scope under Google's policy.                                                      |
| `gmail.compose`              | Create and manage Gmail drafts. Circuit uses this scope to write drafts only. While the scope name implies send capability, Circuit does not call Gmail's send endpoint, so no message is ever sent. |
| `calendar.readonly`          | See and download calendars the signed-in user can access. Required for listing calendars and reading event details across them.                                                                      |
| `calendar.events.readonly`   | View events on the user's calendars. Required for listing events and running free/busy queries.                                                                                                      |
| `contacts.readonly`          | Read the user's Google Contacts. Required for the contact list and search operations.                                                                                                                |

Circuit uses the **OAuth 2.0 authorization code flow** with offline access (a refresh token), so the connection stays alive in the background without periodic reauthentication.

<Note>
  Circuit does not request `gmail.send`, `calendar.events` (write), `contacts` (write), or any Drive scopes. The integration cannot send mail, modify your calendar, write contacts, or read Drive files even if an agent is instructed to do so. For Drive access, see [Google Drive](/admin/integrations/feeds/google-drive).
</Note>

## For IT and security teams

Circuit's Google integrations (Google Workspace and Google Drive) authenticate through a single Circuit-owned OAuth client in Google. Google Workspace administrators can control which third-party OAuth apps reach Workspace data through **Security** > **Access and data control** > **API controls** > **Manage App Access** in the Google Admin Console.

Because Circuit requests `gmail.readonly`, which Google classifies as a **restricted** scope, restrictive Workspace tenants will block users at the consent screen until an admin marks Circuit as **Trusted** (full restricted-scope access) or **Limited with specific Google data access** (only the scopes you list, useful for permitting Gmail and Calendar but blocking Drive, for example). Unverified-app restrictions also apply to apps with `gmail.readonly` access and more than 100 users.

Access level changes can take up to 24 hours to propagate. The full Google Workspace walkthrough, role requirements, and how to scope approval to specific organizational units live in [Integration security and admin consent](/it/integration-security).

## Disconnect or rotate access

* **From Circuit**: open **Settings** > **Integrations** > **Google Workspace** and click **Disconnect**. Circuit deletes the stored refresh token immediately.
* **From Google**: at [myaccount.google.com/permissions](https://myaccount.google.com/permissions), find Circuit and click **Remove access**. Circuit will lose access on the next API call.
* **Workspace-wide**: a Workspace administrator can change the app's access level (or block it) in **API controls** > **Manage App Access**. Changes can take up to 24 hours to propagate.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Access blocked: Circuit has not completed the Google verification process&#x22; or &#x22;your admin has not approved this app&#x22;">
    Your Workspace administrator restricts third-party apps that use Gmail's restricted scopes. Ask them to mark Circuit as **Trusted** or **Limited with specific Google data access** in the Google Admin Console. See [Integration security and admin consent](/it/integration-security).
  </Accordion>

  <Accordion title="Gmail search returns nothing for queries that work in Gmail itself">
    The `search_emails` command uses Gmail query syntax (for example, `from:alice has:attachment newer_than:7d`), not OData. Make sure the agent is passing Gmail syntax and not Outlook-style filters.
  </Accordion>

  <Accordion title="Calendar events from a shared calendar are missing">
    The `calendar.readonly` and `calendar.events.readonly` scopes only surface calendars the signed-in user already has access to in Google Calendar. Ask the calendar owner to share the calendar with your account, then retry.
  </Accordion>

  <Accordion title="Agent says &#x22;I drafted the message&#x22; but the email did not arrive">
    By design, Circuit only saves Gmail drafts. Open Gmail, find the draft in your Drafts folder, review it, and click **Send** yourself. Circuit will not send mail under any circumstances.
  </Accordion>

  <Accordion title="The integration shows 'Disconnected' after working previously">
    A refresh token can be invalidated by a password change, a Workspace policy change, an admin revocation, or a long period of inactivity. Disconnect and reconnect to issue a new token.
  </Accordion>
</AccordionGroup>

## Reference

* **OAuth flow**: Google OAuth 2.0 authorization code, with `access_type=offline` for a refresh token
* **Scopes requested**: `openid`, `email`, `profile`, `https://www.googleapis.com/auth/gmail.readonly`, `https://www.googleapis.com/auth/gmail.compose`, `https://www.googleapis.com/auth/calendar.readonly`, `https://www.googleapis.com/auth/calendar.events.readonly`, `https://www.googleapis.com/auth/contacts.readonly`
* **Redirect URI**: `https://app.circuit.ai/api/google-workspace-oauth`
* **OAuth app name shown on consent screen**: Circuit
* **Google's own docs**: [OAuth 2.0 scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes), [Choose Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes), [Control which third-party and internal apps access Google Workspace data](https://support.google.com/a/answer/7281227), [Restricted scope verification](https://developers.google.com/identity/protocols/oauth2/production-readiness/restricted-scope-verification)