Google Cloud OAuth app setup

Part A — Create project and enable APIs

1. 1Open console.cloud.google.com and sign in.
2. 2Top bar → click the project dropdown → New Project.
   • Project name: Fiko Email (or your product name)
   • Click Create and wait until the project is ready
   • Select the new project from the top bar dropdown
3. 3Left menu → APIs & Services → Library.
4. 4Search Gmail API → open it → click Enable.
5. 5Back to Library → search Cloud Pub/Sub API → Enable.

   Expected result

   Both Gmail API and Cloud Pub/Sub API should show status Enabled. Pub/Sub is required for real-time push in Part G — enable it now so you do not need to return later.

Part B — OAuth consent screen

6. 6Left menu → APIs & Services → OAuth consent screen.
7. 7Choose User type:
   • External — for any Gmail / Google Workspace customer (most cases)
   • Internal — only if every mailbox is in your single Workspace org
8. 8Fill App information → click Save and Continue:

   Field	Example value	Notes
   App name	Fiko	Shown on Google consent screen
   User support email	[email protected]	Must be a Google account you control
   App logo	(optional)	Not required for Testing
   Application home page	https://fiko.com	Your product URL
   Application privacy policy link	https://fiko.com/privacy	Required before Production publish
   Application terms of service link	https://fiko.com/terms	Required before Production publish
   Authorized domains	fiko.com, fikosrv.com	Domains used in links above
   Developer contact information	[email protected]	Google may email about verification

9. 9On Scopes → click Add or Remove Scopes → filter "Gmail" → add both scopes below (full URLs):

   OAuth scopes Fiko requests

   Scope URL (exact)	Purpose in Fiko
   https://www.googleapis.com/auth/gmail.modify	Read inbox, mark read/unread, move messages — ingest + threading
   https://www.googleapis.com/auth/gmail.send	Send replies from Fiko on behalf of the connected mailbox

   Fiko authorize URL also sets access_type=offline and prompt=consent so refresh tokens are issued reliably. Then Update → Save and Continue.
10. 10On Test users (while app is in Testing) → Add users → enter every support mailbox email that will connect during pilot (e.g. [email protected]).

    Expected result

    In Testing mode, only listed test users can complete OAuth. Refresh tokens may expire after ~7 days until you publish to Production — see CASA ops guide.
11. 11Click Back to Dashboard. Publishing status should show Testing.

Part C — Create OAuth client (Web)

12. 12Left menu → APIs & Services → Credentials.
13. 13Click Create Credentials → OAuth client ID.
14. 14Application type: Web application. Name: Fiko Gmail.
15. 15Under Authorized redirect URIs → Add URI → paste exactly:

    https://msg.fikosrv.com/v2/email/oauth/google/callback

    Expected result

    The URI must match GOOGLE_OAUTH_CALLBACK_URL character-for-character (including http vs https, no trailing slash).
16. 16Click Create. A popup shows Client ID and Client secret. Copy both immediately — you cannot view the secret again later.

Part D — Generate encryption key and set env vars

17. 17Generate EMAIL_ENCRYPTION_KEY (32 random bytes, base64). Run once and reuse the same value on both services:

    node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

    Expected result

    Store in secrets manager. If this key changes, existing stored OAuth refresh tokens cannot be decrypted — agents must reconnect mailboxes.
18. 18On fiko-messaging-service, set:

    GOOGLE_OAUTH_CLIENT_ID=123456789-xxxx.apps.googleusercontent.com
    GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-xxxxxxxx
    GOOGLE_OAUTH_CALLBACK_URL=https://msg.fikosrv.com/v2/email/oauth/google/callback
    EMAIL_ENCRYPTION_KEY=your-base64-32-byte-key
    GMAIL_PUBSUB_TOPIC=projects/YOUR_GCP_PROJECT/topics/gmail-push

    • GMAIL_PUBSUB_TOPIC: set after Part G topic is created, or leave unset for polling-only mode
    • GOOGLE_OAUTH_CALLBACK_URL must match Google Console redirect URI exactly
19. 19On fiko-core-service, copy client ID, secret, and encryption key (callback URL not required on core):

    GOOGLE_OAUTH_CLIENT_ID=...
    GOOGLE_OAUTH_CLIENT_SECRET=...
    EMAIL_ENCRYPTION_KEY=...

20. 20Redeploy / restart both services after updating env.

Part E — Verify OAuth

21. 21In Fiko dashboard → Apps → Email → Add new → Connect mailbox → Connect Google.
22. 22After Allow, browser redirects back to Fiko. Finish setup → connected mailbox shown.

    Expected result

    If you see redirect_uri_mismatch, fix URI in Google Console vs GOOGLE_OAUTH_CALLBACK_URL.
23. 23Send test email → open Chats → reply from Fiko.

Part G — Gmail Pub/Sub push (production, recommended)

Production flow: Gmail users.watch (labelIds: INBOX) → Google Pub/Sub topic → POST /v2/email/gmail/push/:channelId → immediate sync. Cron at 2 AM renews watch (Gmail watch expires in ≤7 days).

24. 24Pub/Sub → Topics → Create topic → ID: gmail-push.
25. 25Topic → Permissions → Grant access → principal [email protected] → role Pub/Sub Publisher → Save.

    Expected result

    Without this permission, Gmail users.watch fails silently or logs permission errors.
26. 26Set env on messaging-service and redeploy:

    GMAIL_PUBSUB_TOPIC=projects/YOUR_GCP_PROJECT/topics/gmail-push

27. 27Connect (or reconnect) Gmail channel in Fiko — after OAuth attach, Fiko calls Gmail users.watch with the topic above.

    Expected result

    messaging-service log: Gmail Pub/Sub watch enabled for channel ...
28. 28Get channel ID from Fiko (Apps → Email → Channel Details → Provider channel ID or URL).
29. 29Pub/Sub → Subscriptions → Create subscription — fill every field:

    Push subscription fields

    Field	Value	Notes
    Subscription ID	gmail-push-{channelId}	One subscription per Gmail channel
    Select a Cloud Pub/Sub topic	gmail-push	Topic from step 24
    Delivery type	Push	Not Pull
    Endpoint URL	https://msg.fikosrv.com/v2/email/gmail/push/{channelId}	Replace {channelId} with real UUID
    Enable authentication	Unchecked	Fiko endpoint is public HTTPS; OIDC optional later
    Enable payload unwrapping	Checked	Delivers Gmail notification JSON directly
    Acknowledgement deadline	10 seconds (default)	Increase only if Fiko sync is slow
    Message retention duration	7 days (default)
    Retry policy	Retry immediately (default)
    Dead-letter topic	(none)	Optional for ops monitoring

    Expected result

    Each new Gmail channel needs a new push subscription because the endpoint path includes :channelId.
30. 30Send test email → chat should appear within seconds.