Gmail OAuth 2.0 overview

How PayPulse Cloud uses OAuth 2.0 for secure Gmail access.

PayPulse Cloud fetches rental and retail invoices directly from a user’s Gmail inbox. Rather than relying on IMAP or app passwords, it uses the OAuth 2.0 authorization framework together with the Gmail API v1.

Why OAuth 2.0 instead of IMAP or app passwords

Traditional Gmail access via IMAP requires either the user’s account password or a Google app password — both of which grant broad, persistent access to the entire inbox. OAuth 2.0 addresses this with a scoped, time-limited delegation model:

• Minimal scope: PayPulse only requests gmail.readonly, giving it read access to the inbox without the ability to send, delete, or modify messages.
• Short-lived access tokens: Access tokens expire after one hour, limiting the window of exposure if a token is ever compromised.
• Refresh tokens: Long-lived refresh tokens allow the backend to reacquire access tokens automatically, without prompting the user again.
• Revocable authorization: Users can revoke PayPulse’s Gmail access from their Google Account settings at any time, without changing their password.
• Encrypted storage: All tokens are stored encrypted at rest in AWS Secrets Manager.

Authentication flow

1. User logs in to PayPulse

   The user authenticates with their PayPulse email and password via POST /v1/auth/login. The backend verifies credentials and returns a short-lived JWT access token.

2. User grants Gmail access via Google Sign-In on iOS

   In a separate step, the user taps “Connect Gmail” in the iOS app. The app invokes the Google Sign-In SDK, which presents a native OAuth consent screen. The user grants the gmail.readonly scope. No client secret is required — the iOS app is a public OAuth client.

3. OAuth tokens sent to backend and stored in Secrets Manager

   The iOS app sends the resulting access_token, refresh_token, expires_in, scope, and Google user info to POST /v1/auth/gmail-tokens, authenticated with the JWT from step 1. The backend validates the tokens, fetches Google user info, checks for account switches, and persists the token bundle in AWS Secrets Manager under the key gmail/user/{user_id}.

4. Backend uses stored tokens to access Gmail API

   Lambda functions that need inbox access retrieve the stored tokens from Secrets Manager, automatically refresh the access token if it has expired, and use the Gmail API v1 to search for and download invoice emails.

Security features

Feature	Detail
Short-lived access tokens	1-hour expiration minimizes exposure if a token is leaked
Refresh tokens	Enable seamless re-authorization without user interaction
Encrypted storage	AWS Secrets Manager encrypts all token data at rest
Proactive refresh	Tokens are refreshed if they expire within the next 5 minutes
Account consistency check	Backend warns when the user connects a different Google account than the one previously linked
Automatic cleanup	Expired or revoked refresh tokens are deleted from Secrets Manager so the user is prompted to reconnect

Detail pages

iOS integration

How the PayPulse iOS app uses the Google Sign-In SDK and what it sends to the backend.

Token management

How the backend stores, validates, refreshes, and rotates OAuth tokens.

Secrets Manager

How AWS Secrets Manager is configured for token and credential storage.