Skip to main content
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 below.

​
Connect Google Workspace

1

Open the Google Workspace integration in Circuit

In Circuit, open Settings > Integrations and choose Google Workspace.
2

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

Review and consent to the requested scopes

Google shows a consent screen listing each scope Circuit requests. Review them (see 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.
4

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.

​
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
ScopeWhy Circuit needs it
openid, email, profileStandard OpenID Connect scopes. Circuit uses these to identify and label your connected account.
gmail.readonlyView your Gmail messages and settings. Required for listing, searching, and reading mail. This is a restricted scope under Google’s policy.
gmail.composeCreate 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.readonlySee and download calendars the signed-in user can access. Required for listing calendars and reading event details across them.
calendar.events.readonlyView events on the user’s calendars. Required for listing events and running free/busy queries.
contacts.readonlyRead 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.
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.

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

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

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

​
Reference