Google Workspace Setup

Overview

Switchboard connects to Google Workspace services (Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Chat, Contacts, and Meet) from one dashboard page. Pick the services you need, click Connect with Google, and every granted service is configured from that single consent.

Hosted orgs use Switchboard's shared Google OAuth client by default. Admins can optionally paste an organization-owned client under Advanced if they need to skip Google verification. The unified setup page lives at /integrations/google/setup. Individual Google service pages redirect there, so there is only one way to connect.

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:

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

3. Configure the OAuth consent screen

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.

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:

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 — Use Switchboard's shared client (default)

1. Open /integrations/google/setup.
2. Check the services you need and click Connect with Google.
3. Complete the consent screen. Every granted service is configured automatically for your account.

Option B — Per-org, via the dashboard (advanced)

1. As an org admin, open /integrations/google/setup and expand Advanced.
2. Paste the Client ID and Client Secret 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.

Option C — 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.

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.

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.