OAuth 2.0
OAuth 2.0 lets you give an application limited access to your account at another service without giving it your password. You are redirected to that service, you approve a named list of permissions, and the application receives tokens instead of credentials. Connect uses it for Google sign-in — the only sign-in it has — and for mailbox access to Gmail and Microsoft Graph.
The flow, one step at a time#
The application sends you to the provider with a client identifier, a redirect target and the scopes it is asking for.
Result You are on the provider's own page. Your password is typed there, into them, and never passes through the application.
You approve, or you do not.
Result The provider redirects back with a short-lived authorisation code. The code is single-use and useless on its own.
The application exchanges the code, server to server, for tokens.
Result It receives a short-lived access token and, if it asked for durable access, a refresh token. The exchange proves the application is who it claims, which is why the code alone is not enough.
It calls the provider's API with the access token until that expires, then quietly exchanges the refresh token for a new one.
Result Mail keeps syncing without anyone signing in again — which is the whole point, and the whole risk.
Two details protect the middle of that sequence. The redirect target must be registered in advance, so a code cannot be delivered somewhere else. And the target must be HTTPS, which is one reason there is no configuration of Connect where a person signs in over plain HTTP.
A scope is what, not who#
This is the most common misreading. A scope names a capability — read this mailbox, send as this account — and it says nothing about who is holding the token. Anything with the token has exactly that capability, whether or not the person who approved it is anywhere nearby. That is why scopes are requested narrowly and why the difference between reading mail and sending mail is a boundary rather than a detail.
- Access token
- Short-lived, sent with each API call. Expiry limits the damage of a leak to minutes.
- Refresh token
- Long-lived. It mints new access tokens indefinitely until it is revoked. Treat it exactly as you would a password.
- Consent
- The person's approval, revocable from the provider's own account settings. Revoking there stops Connect syncing that mailbox, whatever Connect's own records say.
- Client secret
- The application's proof of identity in the token exchange. It belongs in a secret store, never in a repository or a screen.
Does Connect use OAuth 2.0?#
Used, for two distinct purposes. Google OAuth is the only way to sign in to Connect; there is no password login, and password_sign_in is recorded as not implemented rather than as an option somebody has turned off. Separately, mailbox access uses OAuth against Gmail and Microsoft Graph — IMAP and SMTP mailboxes are the exception and authenticate their own way.
Provider credentials are sealed by settings_store on every save and are never echoed back to a screen. If a screen appears to show you a stored secret, it is showing you a masked stand-in. A workspace administrator who has lost a credential replaces it; nobody reads it back out.
How this breaks in practice#
| Symptom | Usual cause | Where it is fixed |
|---|---|---|
| A mailbox stops syncing with no configuration change | Consent was revoked at the provider, or the password change invalidated the grant | The provider's account settings, then reconnect the mailbox |
| Reconnecting works, then fails again days later | The refresh token is being replaced without the new one being stored | The integration, not the provider |
| Sending fails while reading works | The grant covers read scopes only | Re-consent with the send scope; a role that sends needs it |
| Everything fails after a redirect target changed | The new target is not registered with the provider | The provider's client configuration |
The general lesson is that OAuth failures present as intermittent product faults. A mailbox whose grant has gone stops producing new mail without producing an error a person would notice, which is exactly why mailbox health is surfaced as its own signal rather than inferred from the word "connected".
Questions#
Does Connect see my Google password?
No. The password is typed on Google's own page, and Connect receives tokens. That property is the reason delegated authorisation exists, and it holds for Microsoft Graph mailboxes as well.
What happens if I revoke access at Google?
The refresh token stops working immediately, so sync and sending stop for the mailboxes covered by that grant. Connect will show the mailbox as unhealthy rather than silently reporting nothing new. Records already stored stay where they are.
Is OAuth how a developer authenticates to the Connect API?
That is a different mechanism. OAuth here is about Connect reaching your provider accounts, and about signing a person in. Machine access to Connect uses integration keys, which are issued, scoped and revoked separately.