Connecting Your Google Account to a Workflow via OAuth

Before Gmail, Sheets, or Calendar actions can run for you, your Google account needs to be connected. This release adds that connect flow: a start endpoint that kicks off Google's OAuth consent screen, and a callback endpoint that finishes it once you've approved access.

Why it isn't a direct browser flow

Google's OAuth requires a real, fixed HTTPS redirect address to send you back to — and connector-worker, the service that actually holds the credential vault, doesn't have a public address of its own by design. So your browser never talks to it directly. Instead, gateway-portal (the dashboard you're actually looking at) is the one with a real address, and it calls connector-worker server-to-server, authenticated with an internal key plus your resolved user ID, to start and complete the flow on your behalf.

What's protecting the handoff

The OAuth flow's state — the token that proves the callback matches the request that started it — is signed and time-limited, so it can't be replayed or forged, the same pattern already used elsewhere on the platform for a comparable Gmail OAuth flow, built independently here since the two services don't share that code directly. And connector-worker uses its own dedicated Google OAuth client, not the identity provider's, not the email system's — so if one credential is ever rotated, it doesn't affect the others.

What gets stored

Once you approve, the resulting tokens are encrypted at rest (AES-256-GCM) before they're written to the database — nothing usable sits in plain text, and the encryption matches the standard already used for other stored credentials on the platform.

This connect flow is the piece that makes the rest of this release possible: Gmail, Sheets, and Calendar actions, plus the new Gmail polling trigger for Workflows, all depend on an account having gone through it first.