Gmail OAuth

The Gmail integration lets the Inbox pull customer mail automatically. Tokens are stored per tenant. The steps below are a one-time Google Cloud setup so users can hit Connect Gmail in Settings → Integrations.

What you need

• A Google account with permission to create a Cloud project.
• The public host where FixControl runs (e.g. https://app.example.com). The OAuth redirect must match it exactly.

Step 1: Google Cloud project

1. Go to console.cloud.google.com and create a new project, e.g. fixcontrol-prod.
2. Open APIs & Services → Library, search for Gmail API, and click Enable.
3. (Optional, for push notifications later) also enable Cloud Pub/Sub API.

Step 2: OAuth consent screen

1. APIs & Services → OAuth consent screen.
2. Pick External (Internal/Workspace-only works too, but then every user must be in the same Workspace).
3. Fill in app name, support email, and developer contact. Logo and homepage can be placeholders to start.
4. Under Scopes, add gmail.readonly, gmail.modify, openid, email, and profile — these are the exact five FixControl asks for during consent.
5. Test users — add every Gmail address you plan to connect while the app is in Testing mode. This is the most common pitfall: a user not on this list gets access_denied on the consent screen.
6. Only flip to In production after Google verifies the app. For internal tools Testing is usually fine — just be aware of the 100 test-user cap and the 7-day refresh-token expiration that comes with it.

Step 3: OAuth Client ID + redirect URI

1. APIs & Services → Credentials → Create credentials → OAuth client ID.
2. Application type: Web application.
3. Authorized redirect URIs: add:

`` https://<your-host>/api/auth/gmail/callback ``

You can register multiple redirect URIs if you want to share one client across environments.

1. Click Create and copy the Client ID and Client secret. The secret is no longer readable after you leave this dialog — store it in your secret manager right away. Provide the Client ID, Client secret, and redirect URI to FixControl during initial setup.

Heads up: the redirect URI in Google Cloud must match the one configured in FixControl byte for byte. A trailing slash, http vs https, or app.example.com vs www.app.example.com will produce redirect_uri_mismatch.

Step 4: Connect from FixControl

1. Sign in as a tenant admin and open Settings → Integrations.
2. Click Connect Gmail. You'll be redirected to Google's consent screen.
3. Pick the Gmail account, approve the scopes, and you'll land back on the Integrations page with the new Gmail connection listed.

Within a few minutes the Inbox will start pulling unread mail. You can connect multiple Gmail accounts per tenant — recipient routing decides which To: address belongs to which tenant.

(Optional) Pub/Sub push

For near-realtime intake you can register a users.watch:

1. Create a Pub/Sub topic, e.g. projects/<project>/topics/gmail-fixcontrol.
2. Grant gmail-api-push@system.gserviceaccount.com the Pub/Sub Publisher role on that topic.
3. Create a push subscription whose endpoint is https://<your-host>/api/gmail/webhook?token=<verify-token>, where the verify token is a random string of 32+ characters you also provide to FixControl.

Gmail watches expire after ~7 days — FixControl re-registers them automatically as long as the connection stays active.

FAQ

I'm getting `redirect_uri_mismatch`. Compare the redirect URI configured in FixControl to the URI under Credentials → OAuth client → Authorized redirect URIs character by character. Google's console can lag a minute after saving — give it a moment.

`access_denied` on the consent screen. The app is in Testing mode and the Gmail address isn't a test user. Add it under OAuth consent screen → Test users.

No `refresh_token` after connecting. Shouldn't happen — FixControl forces prompt=consent. If it does, revoke access at myaccount.google.com/permissions and reconnect.

Do I have to get the app verified by Google? Only if you go beyond 100 test users or you don't want users to see the unverified-app warning. Internal installs typically don't need verification.