When to disconnect
Two common reasons. The first is routine: you no longer use the connected mailbox for invoices (you've changed providers, the role at the company changed, you've shifted to forwarding-only). Disconnect cleans up the connection, revokes the token at the provider so we can't fetch from it any more, and stops cluttering your settings page.
The second is incident response: the connected account has been compromised, the OAuth token might have leaked, or a security alert from Google / Microsoft has flagged the connection. In that case, the order matters — disconnect from TaxItEasy first, then change the upstream account's password.
If you instead want to keep the connection but rotate it (re-grant OAuth on the same mailbox), disconnect + re-connect is the cleanest path. There's no separate "refresh tokens" action.
The walk-through
Step 1 — open the integration page
Settings → Email integration. The page lists every connected account with its provider, the email address, the connection status (Active / Needs re-auth / Disconnected), and the time of the last successful poll.
Step 2 — disconnect
Find the account you want to remove. Click Disconnect (some platforms label it Remove). A confirmation modal asks you to confirm — disconnects are not destructive but they're not undoable in one click either, so we want the explicit confirmation.
Click Confirm. Two things happen, in this order:
- Local token zeroing. The encrypted OAuth token in our database is overwritten with zero bytes. Any in-flight sync job that reads the row after this moment gets an empty token and exits cleanly without making an API call to Google / Microsoft.
- Provider-side revoke. Within a few seconds, we call the provider's revoke endpoint:
- Google:
POST https://oauth2.googleapis.com/revoke?token=<refresh_token>— Google invalidates the token immediately at their side. - Microsoft: there is no public single-token revoke endpoint on the Microsoft identity platform. We rely on local-wipe (above) plus the token's natural expiry (typically 90 days for personal accounts, configurable for Microsoft 365 tenants).
- Google:
The audit log records the disconnect with one entry: email.disconnect, with fields provider, email, revoked_at_provider: true/false, revoke_attempts: <n>. You can inspect it in Settings → Audit log.
Step 3 — verify it's gone
The account disappears from the integration list. No further polls happen against it; no further mail flows from it into your Documents.
You can also verify on the provider's side:
- Google:
myaccount.google.com → Security → Third-party connections. The TaxItEasy entry should be gone (or have its access removed, depending on Google's caching). - Microsoft:
account.microsoft.com → Privacy → Apps and services. Similar.
If the provider still shows TaxItEasy as a connected app after a few minutes, the local revoke succeeded but the provider-side state hasn't propagated yet. This is rare; Google usually updates within seconds. You can manually remove the app from the provider side too — it doesn't hurt.
What changes when you disconnect
- Documents we already extracted from past emails stay. Disconnecting doesn't delete history. The invoices and receipts you've accumulated from this mailbox are still in your Documents.
- The connected email address can be re-connected later. Full OAuth consent flow again; the prior history is preserved across reconnections.
- Your inbound forwarding address (
u-…@in.taxiteasy.org) is unaffected. That's a separate path; disconnecting Gmail OAuth doesn't break forwarding rules in Gmail (those still send mail to your forwarding address as long as the rules exist). - In-flight polls are cancelled. If a poll was running at the moment of disconnect, it sees the zeroed token on its next read and exits without processing.
- Webhook / push subscriptions are torn down. For Gmail (which uses push notifications via Cloud Pub/Sub in production), the watch is cancelled at Google's side. No more push events arrive for that account.
Why we revoke at the provider, not just locally
If we only erased the token locally without revoking it at Google, an attacker who had previously exfiltrated the token (in a database leak, a misplaced backup, a developer's compromised laptop) could keep using it until it naturally expires — up to 6 months for some Google tokens.
Provider-side revoke ensures even if someone has the token, it stops working immediately. The cost is one extra API call per disconnect, and a brief window (under 5 seconds typically) between local zeroing and provider acknowledgement. The benefit is hard-revoke instead of soft-revoke.
This is also part of the CASA Tier 2 requirements for Google OAuth verification — we're contractually required to call the revoke endpoint on user-initiated disconnects.
What we cannot revoke at the provider
Microsoft's identity platform doesn't expose a public single-token revoke endpoint for personal / Microsoft 365 accounts (only enterprise tenants have admin-side revoke via the conditional-access API). For Microsoft connections, we:
- Zero the token locally (same as Google).
- Rely on the token's natural expiry.
- For paranoid users, recommend revoking the app at
account.microsoft.com → Privacy → Apps and services → TaxItEasy → Removeafter disconnecting.
This is a Microsoft platform limitation, not a TaxItEasy choice. We'd revoke at their side if they exposed an API for it.
Cascade-revoke
If you delete your TaxItEasy account entirely (see delete your account), every OAuth connection is auto-disconnected as part of the deletion flow. We call revoke on every active token before the 30-day soft-delete window begins, so even during the grace period there's no live connection to Google / Microsoft. This is part of the same CASA Tier 2 compliance set.
Troubleshooting
Disconnect button didn't seem to do anything. Refresh the page. If the account still shows as connected, check Settings → Audit log for email.disconnect entries; if the disconnect succeeded server-side, it's a UI cache issue. Hard-refresh (Cmd+Shift+R / Ctrl+Shift+R) clears it. If the audit log shows no email.disconnect entry, the click didn't reach the server — try again, and if it still fails, write to [email protected] with [TECHNICAL] and the timestamp.
Provider revoke failed. We retry the revoke call 3× with exponential backoff. If Google's endpoint is down at exactly that moment (rare), the audit entry records revoked_at_provider: false, revoke_attempts: 3. We re-attempt on the next prune cycle (every 24 hours). Your token is already zeroed locally, so we can't use it from our side — we just can't tell Google about it yet. The token's natural expiry will eventually catch up.
I want to delete the audit-log entries too. Disconnect doesn't delete audit history — that's by design for compliance. Account deletion does crypto-shred the entire audit trail. See delete your account and export your data.
The Gmail connection went into "Needs re-auth" by itself. Common after a Google security event (password change, suspicious-activity alert) or after 6 months of inactivity. Click Reconnect and walk through the consent screen again. No data is lost; the next poll picks up where the last good one left off.
I want to disconnect every connected account at once. Not currently a single button — disconnect each in turn. If you have many accounts (rare, but possible for power users), or you're doing it for security incident response, write to [email protected] from the account email; we can disconnect everything server-side within a few minutes.
After disconnecting, the same Gmail address still appears in suggestions when I click Connect. That's a browser-side autocomplete remembering what you've typed, not anything we remember. Type a different address or use a fresh browser to confirm the suggestion isn't coming from us.
Related
- Connect Gmail, Outlook, or IMAP — the inverse flow
- Set up email forwarding — the simpler alternative that doesn't need OAuth
- The inbound address explained — the unaffected forwarding path
- Where is my data stored? — what we hold for connected accounts