Meta long-lived token setup and rotation

Admaxxer is a DTC analytics platform with built-in Meta + Google ad ops. Long-lived Meta user access tokens are valid for roughly 60 days, which means every connection you add has a rolling expiry clock that needs proactive rotation. TL;DR: use the Admaxxer OAuth flow (or paste-token flow) to mint a fresh long-lived token, keep the daily `meta-token-expiry` cron enabled, and reauth anytime a connection reports an expiry inside the 7-day warning window. ## Symptoms - Meta spend stops updating on your Admaxxer dashboard after a specific date. - The Meta connection card shows "Token expired" or an amber "Expiring in N days" badge. - Meta Marketing API responses contain `OAuthException` with code 190 (token invalidated). - Your blended MER, CAPI match rate, and Meta-sourced revenue charts show flat lines at the cutover. - Scheduled insight syncs log `Invalid OAuth access token` in the BullMQ worker. ## Root cause Meta exposes two token lifetimes: - **Short-lived user tokens** (~1 hour) — issued at the end of OAuth. - **Long-lived user tokens** (~60 days) — minted by exchanging a short-lived token against `oauth/access_token?grant_type=fb_exchange_token`. Admaxxer always exchanges to a long-lived token before storing it. Even so, 60 days is a hard ceiling. If the token is not rotated or reauthorized before it hits that ceiling, Meta invalidates it and every subsequent call to Meta Marketing API v21.0 returns an OAuth error. Secondary causes: the user changed their Facebook password, revoked the app, or hit a Meta-wide throttle such that repeated requests look like abuse and Meta invalidates the token defensively. ## Fix ### Step 1: Open the Meta connection card Admaxxer -> Connections -> Meta. The card shows the current expiry timestamp and a badge when it is inside the warning window. ### Step 2: Choose OAuth or paste-token - **OAuth flow**: click "Reconnect Meta". Meta redirects you through a consent screen where you select the ad accounts you want Admaxxer to read. Admaxxer exchanges the resulting token for a long-lived token automatically. - **Paste-token flow**: if you are on the App Review-free path, generate a long-lived user access token from Meta's Graph API Explorer, tick `ads_read` and `ads_management`, and paste it into Admaxxer. ### Step 3: Confirm token scopes Admaxxer requires at least `ads_read` and `ads_management`, plus `business_management` if you want Admaxxer to discover ad accounts inside a Business Manager. Missing scopes cause silent 403s on specific endpoints. ### Step 4: Let Admaxxer encrypt and store the token The new token is encrypted with AES-256-GCM and written to `ad_platform_connections`. The card should flip back to green and a backfill sync queues automatically. ### Step 5: Respect the rate limits Meta Marketing API user tokens are budgeted at roughly 200 calls per hour per user token. Reconnecting triggers a burst backfill, so watch the Admaxxer sync log — if you see 80%+ utilization, Admaxxer auto-throttles, but it is worth noting. ## Verify the fix - The Meta card is green with a fresh expiry ~60 days out. - A smoke-test insights call (which Admaxxer runs on reconnect) returns a non-zero row count for the last 7 days of spend. - Your Meta spend chart updates within a few minutes. - The daily expiry cron logs show the new connection's expiry > 30 days from now. ## Prevent it next time - **Keep the `meta-token-expiry` cron enabled.** It runs daily and flags any connection whose expiry is less than 7 days away. - **Turn on email alerts.** Admaxxer can email the workspace owner when a connection is in the warning window. - **Reauth proactively.** If you know an employee is leaving or a Meta Business Manager ownership is changing, reconnect before the change so the token is tied to a stable user. - **Avoid password-protected accounts that churn.** Shared employee credentials often change; pair the Meta connection with an owner-level account that does not rotate passwords often. ## Related guides - [Google Ads refresh token expired](/guides/google-ads-refresh-token-expired) - [Duplicate payment events](/guides/duplicate-payment-events) - [Meta Ads install guide](/documentation/install/meta-ads) ## FAQs **Q: Why 60 days and not forever?** A: Meta intentionally caps long-lived user tokens at about 60 days to limit blast radius if a token leaks. Page and system-user tokens can last longer, but those require Meta Business Manager and App Review. **Q: Can Admaxxer auto-rotate the token without a user click?** A: Admaxxer re-exchanges the token against `fb_exchange_token` when possible, but Meta does not allow indefinite silent rotation. Once the 60-day ceiling is hit, a user has to reauth. **Q: What happens to my data if I miss the rotation window?** A: Syncs pause until you reconnect, but Admaxxer backfills the gap automatically once a new token is in place.