Google Workspace Setup

Overview 1. Create project 2. Enable APIs 3. Consent screen 4. Create client 5. Enter in Switchboard Scopes Troubleshooting

Overview

Switchboard connects to Google Workspace services (Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Chat, Contacts, and Meet) using an organization-owned Google Cloud OAuth client. You create one OAuth client, enable the APIs you need, connect once, and every selected service is configured from that single consent.

Because your org brings its own client, you don't have to wait on Google's app verification or CASA security assessment to start — the app runs in your own Google Cloud project against your users' accounts. The unified setup page lives at /integrations/google/setup in the dashboard. Adding or removing the OAuth client is admin-only; any member can connect their own account once a client is configured.

1. Create a Google Cloud project

Open the Google Cloud Console.
Create a new project (or reuse an existing one) and select it.

2. Enable the APIs you want

Enable an API for each service you plan to connect. In the console go to APIs & Services → Library and enable the ones you need:

Service	API to enable
Gmail	Gmail API
Calendar	Google Calendar API
Drive	Google Drive API
Docs	Google Docs API
Sheets	Google Sheets API
Slides	Google Slides API
Forms	Google Forms API
Tasks	Google Tasks API
Chat	Google Chat API
Contacts	People API
Meet	Google Meet API

Enabling an API is separate from granting a scope. Connecting and approving the consent screen only grants your token the scopes; it does not enable the APIs. If an API is not enabled, calls return 403 "… API has not been used in project … or it is disabled" even though your token is valid. Enable the API from the Library, wait a minute, then try again.

You can enable more later; re-run the connect and Switchboard requests the additional scopes incrementally (it sends include_granted_scopes=true, so previously granted access is preserved).

Go to APIs & Services → OAuth consent screen.
Choose External user type.
Fill in the required app name and support email.
Add the users who will connect as Test users.

7-day refresh-token expiry in Testing. While the consent screen is in Testing status, Google expires refresh tokens after 7 days and members must reconnect. To avoid the weekly re-auth, publish your app (OAuth consent screen → Publish app). Publishing removes the 7-day cap; depending on the scopes you request, Google may require verification before publishing — the bring-your-own-client model lets you defer that until you're ready.

4. Create the OAuth client

Go to APIs & Services → Credentials.
Click Create Credentials → OAuth client ID.
Set the application type to Web application.
Under Authorized redirect URIs, add your deployment's callback URL. The path is always /oauth/callback; use the exact base URL your users hit:

Environment	Redirect URI
Local dev	`http://localhost:8085/oauth/callback`
Production	`https://app.switchboard-mcp.com/oauth/callback`

The setup page shows the exact URI to register for your deployment — copy it from there to avoid typos. Then create the client and copy the Client ID and Client secret.

5. Enter the client in Switchboard

Option A — Per-org, via the dashboard (recommended)

As an org admin, open /integrations/google/setup.
Paste the Client ID and Client Secret and save. They're stored encrypted at rest and scoped to your organization.
Any member can then check the services they want, click Connect with Google, and complete the consent screen. Every granted service is configured automatically for their account.

Option B — Platform-wide, via environment variables

Self-hosters can set a shared client once on the hosted process; it becomes the default for every org that has not supplied its own. An org-supplied client always takes precedence.

environment

export GOOGLE_OAUTH_CLIENT_ID="123456789-abc.apps.googleusercontent.com" export GOOGLE_OAUTH_CLIENT_SECRET="GOCSPX-..."

Scopes requested per service

Enter these full scope strings when Google's console asks you to Manually add scopes — the abbreviated .../auth/... form is rejected as invalid. Only the scopes for the services you select are requested; on a partial consent Switchboard enables only the services whose scopes were actually granted.

Service	Scopes
Gmail	`https://mail.google.com/`
Calendar	`https://www.googleapis.com/auth/calendar`
Drive	`https://www.googleapis.com/auth/drive`
Docs	`https://www.googleapis.com/auth/documents`
Sheets	`https://www.googleapis.com/auth/spreadsheets`
Slides	`https://www.googleapis.com/auth/presentations`
Forms	`https://www.googleapis.com/auth/forms.body` `https://www.googleapis.com/auth/forms.responses.readonly`
Tasks	`https://www.googleapis.com/auth/tasks`
Chat	`https://www.googleapis.com/auth/chat.spaces.readonly` `https://www.googleapis.com/auth/chat.messages`
Contacts	`https://www.googleapis.com/auth/contacts` `https://www.googleapis.com/auth/contacts.other.readonly` `https://www.googleapis.com/auth/directory.readonly`
Meet	`https://www.googleapis.com/auth/meetings.space.created` `https://www.googleapis.com/auth/meetings.space.readonly` `https://www.googleapis.com/auth/meetings.space.settings`

Troubleshooting

A call returns "API has not been used / is disabled" — your token is valid but the service's API is not enabled. Enable it from APIs & Services → Library (step 2), wait ~1 minute, then try again.
Tokens stop working after ~7 days — your consent screen is in Testing status. Reconnect from the setup page, or publish your app (step 3).
redirect_uri_mismatch — the redirect URI in the console must exactly match <BASE_URL>/oauth/callback, including scheme and host. Copy the value shown on the setup page.
A service you enabled isn't connected — make sure you both enabled its API (step 2) and left it checked during connect; partial grants only enable services whose scopes were approved.

Open Google Workspace setup →