Overview
Gmail integration allows PassAgent’s reset engine to read password reset emails automatically. When you initiate a password reset, the engine monitors your inbox for the reset email, extracts the reset link or OTP code, and continues the flow without manual intervention.Connect Gmail
Authorize
Click Connect Gmail. You’ll be redirected to Google’s consent screen.PassAgent requests these OAuth scopes:
| Scope | Purpose |
|---|---|
gmail.readonly | Read emails to find reset links and OTP codes |
gmail.modify | Mark processed reset emails as read |
PassAgent uses
prompt: consent in the OAuth flow to always request a fresh refresh token, ensuring reliable long-term access without re-authorization.How email monitoring works
During an active password reset flow:- Trigger: the reset engine submits the password reset form on the target service
- Poll: PassAgent monitors your Gmail inbox using service-specific search queries (e.g.,
from:accounts@netflix.com subject:password reset) - Extract: when the reset email arrives, the engine parses the HTML and text content to find reset links or OTP codes
- Follow: the extracted link is opened in the automated browser, or the OTP code is entered into the reset form
- Cleanup: the processed email is marked as read
Privacy controls
- PassAgent only reads emails during active reset flows that you initiate
- Email access is scoped to specific sender patterns and subjects defined in the service registry
- No emails are stored, forwarded, or used for any purpose beyond the current reset
- You can disconnect Gmail at any time from Dashboard > Integrations
Token storage
OAuth tokens are stored in your Supabase account record:- Tokens are encrypted at rest using server-side encryption when
isTokenEncryptionEnabled()is active - Access tokens are refreshed automatically when expired
- Refresh tokens persist until you disconnect the integration
Disconnect Gmail
Navigate to Dashboard > Integrations and click Disconnect on the Gmail card. This:- Revokes the OAuth tokens with Google
- Deletes stored tokens from the database
- Disables email monitoring for future resets
After disconnecting, password resets will pause when they reach the “waiting for email” step and ask you to manually provide the reset link or OTP code.
Troubleshooting
| Issue | Solution |
|---|---|
| Reset email not detected | Check your spam folder. The engine searches specific sender patterns — the email may use a different sender address. |
| Token expired | Go to Integrations and click Refresh. If that fails, disconnect and reconnect. |
| ”Insufficient permissions” error | Reconnect Gmail and ensure both scopes are granted on the consent screen. |
| Multiple Gmail accounts | PassAgent connects one Gmail account per user. To switch accounts, disconnect and reconnect with the desired account. |