Gmail OAuth

Gmail-koppeling laat de Inbox automatisch klantmail ophalen. De tokens worden per tenant opgeslagen. Wat je hieronder doet is eenmalig het Google Cloud-project opzetten zodat gebruikers in Settings → Integraties op Verbind Gmail kunnen klikken.

Wat je nodig hebt

• Een Google-account met rechten om een Cloud-project aan te maken.
• De publieke host waar FixControl draait (bijv. https://app.example.com). De OAuth-redirect moet daar exact op matchen.

Stap 1: Google Cloud project

1. Ga naar console.cloud.google.com en maak een nieuw project aan, bijvoorbeeld fixcontrol-prod.
2. Open APIs & Services → Library en zoek op Gmail API. Klik op Enable.
3. (Optioneel, voor push-notificaties later) zoek ook Cloud Pub/Sub API en zet die aan.

Stap 2: OAuth consent screen

1. APIs & Services → OAuth consent screen.
2. Kies External (interne Workspace-only werkt ook, maar dan moeten alle gebruikers in dezelfde Workspace zitten).
3. Vul app-naam, support-email en developer-contact in. Voor logo en homepage mag je in eerste instantie placeholders gebruiken.
4. Bij Scopes voeg je gmail.readonly, gmail.modify, openid, email en profile toe — exact deze vijf vraagt FixControl tijdens consent.
5. Test users — voeg hier elk Gmail-adres toe dat je gaat verbinden zolang de app in Testing-modus staat. Dit is de meest voorkomende valkuil: een niet-toegevoegde gebruiker krijgt access_denied op het consent-scherm.
6. Pas als je de app door Google laat verifiëren mag je In production zetten. Voor interne tools blijft Testing doorgaans prima — alleen het 100-test-user-limiet en de 7-daagse refresh-token expiratie zijn dan om rekening mee te houden.

Stap 3: OAuth Client ID + redirect URI

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

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

Je kunt meerdere redirect-URIs registreren als je verschillende omgevingen met dezelfde client wilt delen.

1. Klik Create en kopieer de Client ID en Client secret. Het secret is na deze schermen niet meer leesbaar — sla 'm meteen op in je secret store. Geef de Client ID, Client secret en redirect URI aan FixControl tijdens de initiële setup.

Let op: de redirect URI in Google Cloud moet byte-voor-byte gelijk zijn aan de URI die in FixControl is geconfigureerd. Een trailing slash, http vs https, of app.example.com vs www.app.example.com levert redirect_uri_mismatch op.

Stap 4: Verbinden in FixControl

1. Log in als tenant-admin en open Settings → Integraties.
2. Klik Verbind Gmail. Je wordt doorgestuurd naar het Google consent-scherm.
3. Kies het Gmail-account, sta de scopes toe, en je komt terug op de Integraties-pagina met de nieuwe Gmail-koppeling in de lijst.

De Inbox begint nu binnen enkele minuten ongelezen mails op te halen. Je kunt meerdere Gmail-accounts per tenant koppelen — recipient-routing bepaalt welk To:-adres bij welke tenant hoort.

(Optioneel) Pub/Sub push

Voor realtime intake kun je users.watch aanzetten:

1. Maak een Pub/Sub topic, bijv. projects/<project>/topics/gmail-fixcontrol.
2. Geef gmail-api-push@system.gserviceaccount.com de rol Pub/Sub Publisher op dat topic.
3. Maak een push-subscription met endpoint https://<your-host>/api/gmail/webhook?token=<verify-token>, waarbij de verify token een willekeurige string van 32+ tekens is die je ook aan FixControl doorgeeft.

Watches verlopen na ~7 dagen — FixControl registreert ze automatisch opnieuw zolang de connectie actief is.

Veelgestelde vragen

Ik krijg `redirect_uri_mismatch`. Vergelijk teken voor teken de redirect URI die in FixControl is geconfigureerd met de URI in Credentials → OAuth client → Authorized redirect URIs. Cache van de Google-console kan vertraagd zijn — wacht een minuut na opslaan.

`access_denied` op het consent-scherm. De app staat in Testing en het Gmail-adres is geen test user. Voeg toe onder OAuth consent screen → Test users.

Geen `refresh_token` na connect. Dit zou niet moeten gebeuren — FixControl vraagt prompt=consent af. Trek desnoods de toegang in via myaccount.google.com/permissions en verbind opnieuw.

Moet ik de app door Google laten verifiëren? Alleen als je breder dan 100 test users uitrolt of als de gebruikers de scope-waarschuwing niet mogen zien. Voor interne installaties hoeft dit niet.