# Connect Google Workspace

Canonical URL: https://docs.fuse.init.inc/integrations/google-workspace/setup

Configure Google Workspace OAuth and create a verified Init connection.



## Before you start [#before-you-start]

**Engine operator** provisions one Google Cloud OAuth client for the Init platform. **Connection admin/user** grants consent for their Google Workspace tenant when connecting.

You need:

* A Google Cloud project with the Google Workspace APIs you intend to call enabled (for example Admin SDK, Drive, Docs, Calendar).
* Access to create OAuth client credentials in that project.
* For Directory or domain-wide admin APIs, a Google Workspace admin account that can consent to those scopes.
* The engine public base URL so the redirect URI matches production.

## Configure the provider [#configure-the-provider]

### One-time platform OAuth app (**Engine operator**) [#one-time-platform-oauth-app-engine-operator]

1. In Google Cloud Console, open **APIs & Services → Credentials**.
2. Configure the OAuth consent screen for a web application. Include only the scopes Init will request for the actions you expose; do not add broad scopes “just in case.”
3. Create an OAuth client ID of type **Web application**.
4. Add the authorized redirect URI exactly as:

   `{FUSE_PUBLIC_URL}/v1/oauth/google_workspace/callback`

   Replace `{FUSE_PUBLIC_URL}` with your deployed Fuse public URL (no trailing slash).
5. Copy the client ID and client secret into the Fuse environment as `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET`. Never commit these values.
6. If the app is still in Testing, add every Workspace admin or user who must complete Connect as a test user on the consent screen.

### Per-customer authorization (**Connection admin/user**) [#per-customer-authorization-connection-adminuser]

No Google Cloud credentials are created per customer. Each connection runs Google’s authorization-code consent for that Workspace identity.

## Connect to Init [#connect-to-init]

1. **Connection admin/user** starts a Google Workspace Connect session from the customer product that embeds Init Connect.
2. Complete Google sign-in and consent for the requested scopes.
3. Init exchanges the authorization code at the platform callback and stores the connection. No customer-submitted credential fields are required for this provider.

If Connect asks you to reconnect after new actions are enabled, re-consent so Google returns the expanded grant.

## Permissions [#permissions]

Action-required Google scopes are listed on the generated provider scope matrix. Prefer least privilege.

**Baseline identity scopes** (runtime consent policy, not action-declared): Init also requests `openid`, `https://www.googleapis.com/auth/userinfo.email`, and `https://www.googleapis.com/auth/userinfo.profile` so the connection can bind the signed-in Google identity. These are separate from action-required API scopes.

Directory and other admin scopes typically require a Workspace administrator to consent. Restricted or sensitive scopes may require Google verification for production apps outside Testing mode.

## Verify the connection [#verify-the-connection]

1. Confirm the connection status is active in Init after consent returns.
2. Run a safe read-only connection test or a low-risk list action (for example listing drives or files) against a non-sensitive resource.
3. Success looks like a completed Connect session, a stored refreshable Google grant, and a successful read response without `401`/`403` from Google.

## Rotate or revoke access [#rotate-or-revoke-access]

* **Rotate platform client secret (Engine operator):** create a new secret in Google Cloud, update `GOOGLE_OAUTH_CLIENT_SECRET`, then retire the old secret after traffic moves.
* **Revoke a customer grant (Connection admin/user):** remove Init access from the Google Account permissions page or Workspace admin controls, then delete or reconnect the Init connection.
* After scope expansion in Init, reconnect so Google issues a grant that includes the new scopes.

## Troubleshooting [#troubleshooting]

| Symptom                                                    | What to check                                                                                                   |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `redirect_uri_mismatch`                                    | Redirect URI must exactly match `{FUSE_PUBLIC_URL}/v1/oauth/google_workspace/callback`.                         |
| Consent screen blocks non-test users                       | App is in Testing; publish or add the user as a test user.                                                      |
| Admin scopes denied                                        | Signed-in account lacks Workspace admin rights for Directory scopes.                                            |
| Actions fail with insufficient scopes after product change | Reconnect so Google re-consents to the expanded scope set.                                                      |
| Platform env misconfigured                                 | Confirm `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET` are set on Fuse, not in customer Connect forms. |