Google Ads OAuth Re-Auth
Use this runbook when AdPilot loses Google Ads access, a refresh token fails, MFA blocks authorization, or the selected Google Ads account no longer has the required API permissions.
Before You Reconnect
Confirm the Google user and OAuth setup are still valid:
- The Google user can see the target customer account or MCC in Google Ads.
- The Google Ads account is active, billable, and not blocked by policy state.
- The OAuth app is configured for production use, not left in external testing mode.
- The developer token is still approved for Google Ads API access.
- The OAuth client still has the Opius redirect URI configured.
- The re-auth flow requests
https://www.googleapis.com/auth/adwordsand offline access.
If you are using a customer-owned OAuth app, have the OAuth client ID/client secret owner available before reconnecting. If you are using the Opius-managed connector, the customer normally only needs the Google user with account access.
Scope Requirements
| Requirement | Purpose |
|---|---|
https://www.googleapis.com/auth/adwords | Lets AdPilot read Google Ads resources and perform approved campaign operations. |
| Developer token | Lets the app call the Google Ads API; it does not grant account visibility by itself. |
| MCC or customer account access | Determines which ad accounts AdPilot can select and monitor. |
| Offline access | Lets scheduled monitoring refresh access when the user is not present. |
How To Identify Expired Auth
The dashboard shows a provider banner on the AdPilot setup, monitoring, or run detail view when Google Ads needs attention.
| Banner | Meaning | Customer impact |
|---|---|---|
Auth expired | The saved OAuth token can no longer refresh. | Google Ads reads and writes stop. |
Reconnect required | AdPilot cannot confirm account access. | Scheduled monitoring for Google Ads is blocked. |
Missing scope | The connected account did not grant the required Google Ads scope. | Reporting and spend-changing actions remain blocked. |
Account unavailable | The selected customer account is no longer visible from the connected manager account. | AdPilot cannot monitor or launch in that account. |
When Google Ads auth is blocked, AdPilot does not launch campaigns, increase budgets, change bids, or reactivate paused ad sets for Google Ads.
Reconnect Steps
- Open Settings -> Integrations for the AdPilot drone.
- Find Google Ads and select Reconnect. If the dashboard opens a reconnect dialog, use the Reconnect Google Ads button to start OAuth.
- Sign in with the Google user that has access to the target Google Ads manager account or customer account.
- Complete any Google two-step verification or MFA challenge.
- Approve the Google Ads OAuth prompt. The required scope is Google Ads API access.
- After Google redirects back to Opius Drone, confirm the dashboard shows the reconnect success banner.
- Confirm the Google Ads provider card returns to
Connected. - Open the AdPilot monitoring view and confirm the Google Ads schedule is no longer blocked.
If MFA fails, restart reconnect from the same provider card. Do not disconnect the provider unless you want to clear local credentials and account selection.
Google MFA And Token Cadence
Google controls MFA and security challenges. AdPilot cannot skip passkeys, two-step verification, Workspace session prompts, or suspicious-login checks.
Use this cadence for launch readiness:
- Check Google Ads auth monthly and before approving a large launch or budget increase.
- Reconnect immediately after password changes, MFA/passkey changes, revoked app access, or Google Workspace session-control changes.
- If the OAuth consent screen is still in external testing mode, expect refresh-token expiry during testing and move the app to production before relying on scheduled monitoring.
- If Workspace policy forces reauthentication, follow that policy cadence and reconnect before the next AdPilot daily monitor.
What Data Is Preserved
Re-auth updates the Google Ads credential record only. It preserves:
- AdPilot configuration, budget caps, target CPA/ROAS, and rules.
- Approval history, including approved, rejected, expired, and stale approvals.
- Campaign plan drafts and pending recommendations.
- Monitoring history and weekly report history.
- Conversion tracking configuration and event names.
- Existing provider campaign IDs and account mappings when the account is still visible.
Rejected or expired approvals are not revived by reconnecting. A new spend-changing action still requires a new approval.
How Monitoring Resumes
After reconnect succeeds, AdPilot refreshes provider status and unblocks Google Ads scheduled monitoring. The next scheduled daily monitor can read spend, delivery, conversions, provider errors, and pacing again.
Spend-changing actions do not resume automatically from a previous rejected, expired, or stale approval. If AdPilot recommends launch, budget increase, bid-strategy change, or reactivation after re-auth, it sends a new approval card.
Common Recovery Notes
- If the account picker does not show the expected customer account, verify the connected Google user has access through the correct MCC.
- If the banner says
Missing scope, reconnect and accept the full Google Ads permission prompt. - If Google requires MFA during authorization, complete the challenge in the browser window before returning to the dashboard.
- If monitoring still says blocked after reconnect, use AdPilot troubleshooting and confirm the selected account is active.
Return to AdPilot.