Docs · Google Workspace

Google Workspace setup

Connect Gmail, Calendar, Drive, and the rest of Google Workspace with a single sign-in using your organization's own OAuth client.

Overview

Switchboard connects to Google Workspace services (Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Chat, Contacts, and Meet) from one dashboard page. An organization admin must first configure a Google OAuth app. Members then pick the services they need, click Connect with Google, and every granted service is configured from that single consent.

Google Workspace currently requires an organization-owned OAuth client because Switchboard's shared client is still in Google Testing. The unified setup page lives at /integrations/google/setup. Individual Google service pages redirect there, so there is only one way to connect. Tool access is controlled from Policies, the same way as every other integration.

1. Create a Google Cloud project

  1. Open the Google Cloud Console.
  2. 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:

ServiceAPI to enable
GmailGmail API
CalendarGoogle Calendar API
DriveGoogle Drive API
DocsGoogle Docs API
SheetsGoogle Sheets API
SlidesGoogle Slides API
FormsGoogle Forms API
TasksGoogle Tasks API
ChatGoogle Chat API
ContactsPeople API
MeetGoogle 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).

  1. Go to APIs & Services → OAuth consent screen.
  2. Choose External user type.
  3. Fill in the required app name and support email.
  4. 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

  1. Go to APIs & Services → Credentials.
  2. Click Create Credentials → OAuth client ID.
  3. Set the application type to Web application.
  4. Under Authorized redirect URIs, add your deployment's callback URL. The path is always /oauth/callback; use the exact base URL your users hit:
EnvironmentRedirect URI
Local devhttp://localhost:8085/oauth/callback
Productionhttps://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

  1. As an org admin, open /integrations/google/setup.
  2. Paste the Client ID and Client Secret into Configure Google OAuth app and save. They're stored encrypted at rest and scoped to your organization.
  3. Any member can then check the services they want, click Connect with Google, and complete the consent screen.

Platform-wide GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET values do not enable new Google Workspace connects while the shared client remains in Testing, unless self-hosters set GOOGLE_OAUTH_ALLOW_PLATFORM_CLIENT=true.

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.

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