Meta Ads OAuth Re-Auth
Use this runbook when AdPilot loses Meta Business access, the connected user or System User token is revoked, Marketing API permissions change, or the selected ad account or Pixel is no longer available.
Before You Reconnect
Confirm the Meta Business setup is still valid:
- The connected Meta user or System User has access to the target Business portfolio.
- The selected ad account is active, billable, and assigned to that user or System User.
- The configured Pixel or dataset is still assigned to the Business and visible to the connected identity.
- The Meta app still has Marketing API enabled.
- App Review or Business verification still covers the permissions used outside your own business assets.
- Pixel plus server-side CAPI setup is ready if conversion verification is part of the blocker.
If you are using a customer-owned Meta app, have the app ID/app secret owner available before reconnecting. If you are using the Opius-managed connector, the customer normally only needs the Meta user with Business and asset access.
Permission Requirements
| Permission | Purpose |
|---|---|
ads_read | Read campaign, ad set, ad, delivery, insight, and spend state. |
ads_management | Create, update, pause, or reactivate campaign entities after approval or for spend-reducing safety actions. |
business_management | Verify Business assets, ad account assignments, Pixels, and datasets. |
pages_show_list / pages_read_engagement | Needed only when Page-backed creative or organic post assets are in scope. |
How To Identify Expired Auth
The dashboard shows a provider banner on the AdPilot setup, monitoring, or run detail view when Meta Ads needs attention.
| Banner | Meaning | Customer impact |
|---|---|---|
Auth expired | The saved Meta token can no longer be used. | Meta Ads reads, writes, and CAPI publishing checks stop. |
Reconnect required | AdPilot cannot verify current Meta Business access. | Scheduled monitoring for Meta is blocked. |
Missing scope | Required Marketing API permissions were not granted or were removed. | Reporting and spend-changing actions remain blocked. |
Pixel unavailable | The configured Pixel or dataset is no longer visible. | Conversion verification cannot complete. |
When Meta auth is blocked, AdPilot does not launch campaigns, increase budgets, change bids, reactivate paused ad sets, or claim CAPI verification for Meta.
Reconnect Steps
- Open Settings -> Integrations for the AdPilot drone.
- Find Meta Ads and select Reconnect. If the dashboard opens a reconnect dialog, use the Reconnect Meta Ads button to start OAuth.
- Sign in with the Meta user that has access to the target Business Manager, ad account, and Pixel.
- Approve the requested Marketing API permissions.
- After Meta redirects back to Opius Drone, confirm the dashboard shows the reconnect success banner.
- Confirm the Meta Ads provider card returns to
Connected. - Re-run the conversion verification step if the banner mentioned Pixel or CAPI access.
- Open the AdPilot monitoring view and confirm the Meta schedule is no longer blocked.
If your organization uses a System User flow, confirm the System User still has access to the ad account, Pixel, and required assets before reconnecting.
Re-Auth Cadence
Meta auth does not use an AdPilot-defined fixed reconnect cycle. Reconnect when Meta revokes the token, the user or System User loses Business access, App Review permissions change, the selected ad account becomes unavailable, or Pixel/CAPI verification can no longer see the selected asset.
After reconnecting, rerun CAPI setup verification whenever the Pixel, dataset, CAPI endpoint, conversion event, or consent policy changed.
What Data Is Preserved
Re-auth updates the Meta 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.
- Pixel, CAPI endpoint, and conversion event configuration when the same asset remains selected.
- 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 Meta scheduled monitoring. The next scheduled daily monitor can read spend, delivery, conversions, provider errors, rejected ads, and pacing again.
If conversion verification was blocked by Pixel or CAPI access, complete CAPI setup again before relying on conversion-based optimization.
Common Recovery Notes
- If the ad account is missing, verify Business Manager permissions for the connected user or System User.
- If the banner says
Missing scope, reconnect and accept the full Marketing API permission prompt. - If the Pixel is missing, confirm it belongs to the selected Business and ad account.
- If monitoring still says blocked after reconnect, use AdPilot troubleshooting and confirm Meta Business access is active.
Return to AdPilot.