> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/azfar-imtiaz/PayPulse-Cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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}`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="iOS integration" icon="mobile" href="/gmail-oauth/ios-integration">
    How the PayPulse iOS app uses the Google Sign-In SDK and what it sends to the backend.
  </Card>

  <Card title="Token management" icon="refresh-cw" href="/gmail-oauth/token-management">
    How the backend stores, validates, refreshes, and rotates OAuth tokens.
  </Card>

  <Card title="Secrets Manager" icon="lock" href="/gmail-oauth/secrets-manager">
    How AWS Secrets Manager is configured for token and credential storage.
  </Card>
</CardGroup>