Skip to main content

​
Overview

Gmail integration allows PassAgent to read password reset emails during automated reset flows. The integration uses Google OAuth2 with minimal scopes.

​
OAuth flow

​
Initiate authorization

Start the Gmail OAuth2 flow. Returns a URL to redirect the user to Google’s consent screen. 
GET /api/gmail/auth
Authentication: Required Response 200 OK: 
{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&scope=..."
}
Requested scopes:
  • https://www.googleapis.com/auth/gmail.readonly — read email content
  • https://www.googleapis.com/auth/gmail.modify — mark messages as read
The gmail.modify scope is requested only to mark reset emails as read after processing. PassAgent never sends email on your behalf.

​
OAuth callback

Handles the OAuth2 callback from Google after user authorization. 
GET /api/gmail/callback?code={authorization_code}&state={state}
Authentication: Via state parameter This endpoint is called by Google’s OAuth redirect. It exchanges the authorization code for access and refresh tokens, which are stored in Redis with encryption at rest. Response: Redirects to the PassAgent dashboard with a success indicator.

​
Disconnect

Remove the Gmail integration and delete stored OAuth tokens. 
POST /api/gmail/disconnect
Authentication: Required CSRF: Required Response 200 OK: 
{
  "success": true
}

​
Refresh tokens

Manually refresh Gmail OAuth tokens. Tokens are refreshed automatically during reset flows, but this endpoint allows manual refresh. 
POST /api/gmail/refresh
Authentication: Required CSRF: Required Response 200 OK: 
{
  "success": true,
  "expiresAt": "2026-03-04T13:00:00Z"
}

​
Email processing

During a password reset flow, PassAgent monitors your Gmail inbox for reset emails:
  1. Polling: checks for new emails matching the service’s known sender addresses
  2. Parsing: extracts reset links from email HTML and text content
  3. Following: navigates to the reset link in the automated browser
  4. Cleanup: marks the processed email as read
PassAgent only reads emails during active reset flows that you initiate. It does not continuously monitor your inbox or access emails unrelated to the current reset.