Meta token health and reconnection

Meta OAuth tokens have approximately 60-day lifetime (Meta's policy). Wevion auto-refreshes silently when possible. If refresh fails (password changed, app revoked, account suspended), the connector card turns yellow with a Reconnect button. Click it to redo OAuth and restore sync — no data is lost during reconnection.

Who is this for

Mediabuyers seeing a yellow banner on the Meta connector card. Admins setting up alerts to catch token expiry before it bites. Anyone who lost Meta sync after changing their Facebook password.

How Meta tokens work

When you connect Meta, Facebook issues:

• Short-lived access token (~1-2 hour validity) — used for immediate API calls

• Long-lived access token (~60-day validity) — exchanged from the short-lived token + used for ongoing sync

Wevion stores the long-lived token encrypted at rest (META_TOKEN_ENCRYPTION_KEY env). The token is workspace-scoped, never visible to Wevion staff, masked in logs.

Auto-refresh flow

Behind the scenes:

• Every ~50 days (well before the 60-day expiry), Wevion attempts to exchange the long-lived token for a fresh one

• Refresh uses Meta's /oauth/access_token endpoint with the existing token

• Successful refresh: new 60-day token stored, sync continues, no visible change for the user

• Failed refresh: connector card turns yellow with Reconnect button + email + Telegram alert (if connected)

When auto-refresh fails

Common causes:

How to reconnect

Step 1: See the yellow card

At /connect/meta, an affected Meta user shows a yellow card with "Token expired — Reconnect" message.

Step 2: Click Reconnect

The OAuth popup opens (same as initial connect):

• Log in to Facebook (with the same FB account, ideally)

• Grant permissions (same 3 scopes — see meta-102)

• Pick BMs to share with Wevion (same as before)

Step 3: Token saved

The popup closes. Wevion saves the new token. Card turns green within seconds.

Step 4: Sync resumes

Sync picks up where it left off — no data lost. Insights from the disconnected period may be missing if the gap was long (Meta keeps data accessible for 13 months for most metrics, but some Page/audience insights have shorter retention).

Reconnect with a different Facebook account

If the original Meta user is permanently unavailable (employee left, account banned, etc.), have a different teammate reconnect:

1. They open /connect/meta

2. They click Connect (not Reconnect — that one ties to the original user)

3. Their OAuth flow creates a new Meta user record

4. If the new user has access to the same ad accounts, sync resumes

5. The old Meta user record can be archived (admin action)

This is why having multiple Meta users covering the same critical accounts is best practice — see meta-106.

Email and Telegram alerts

7 days before predicted token expiry (if Wevion can detect it from the refresh schedule), you get:

• Email to billing email

• In-app notification (bell icon)

• Telegram message (if bot connected — gs-115)

This gives you a week to reconnect proactively instead of waking up to broken sync.

If refresh fails sooner than expected (e.g. password changed, account suspended), you get the alert at the moment of failure — not 7 days warning.

What happens during the gap

Between token expiry and reconnect:

• No new data syncs from Meta to Wevion

• Existing data preserved in Wevion

• Rules don't fire for the affected ad accounts (rule's data source is stale)

• Cannot launch new campaigns to the affected ad accounts (publish fails with "Token expired")

• Cannot edit campaigns in Wevion for those accounts

• Existing campaigns continue running on Meta (Meta serves them, charges your billing, but Wevion can't read the new data)

So a 1-day gap is fine — you've lost a day of incremental data, easy to backfill on reconnect. A 7-day gap means a week of analytics blind spots.

Token encryption details

• Stored encrypted in meta_token table via AES-GCM

• Key from META_TOKEN_ENCRYPTION_KEY env (Wevion's secret manager)

• Token never logged plaintext

• Decrypted only at API-call time, never persisted in memory beyond the call

• Wevion staff cannot view tokens (no admin tool exposes plaintext)

Reconnect vs Disconnect

For ongoing operations: always Reconnect. Disconnect only for cleanup (departed teammate, switching to another Meta user covering the same accounts).

What you'll see

A healthy Meta user:

• Connector card: green badge, Connected

• Last refresh: recent (within last 50 days)

• Ad accounts syncing every 15 min

An unhealthy Meta user:

• Yellow card: "Token expired — Reconnect"

• Last refresh: stale

• Sync stopped for that user's ad accounts

• Banner on Wevion dashboard: "Meta connection needs attention"

Common issues

• Reconnect popup blocked: enable popups for app.wevion.ai.

• Reconnect succeeds but card still yellow: refresh after 60s; if persistent, contact support with meta_user_id.

• Cannot reconnect "Account locked": resolve Facebook lock first (Facebook will email instructions).

• Reconnect creates a new Meta user instead of refreshing: you authenticated with a different Facebook account. Use the original or accept the new user (admin can archive old).

• Sync didn't resume after successful reconnect: 15-min cycle delay. If still stuck after 30 min, hit the Force sync button on the ad account detail drawer.

• Token expires before the 7-day warning email: rare — happens if account was suspended (Wevion can't predict the suspension). React to the failure email immediately.

Best practices

• Connect at least 2 Meta users to critical workspaces (redundancy)

• Whitelist Wevion email + Telegram in your notification settings so token alerts get through

• Update FB password sparingly — every change forces reconnect for tokens from that account

• Don't revoke Wevion from Facebook app settings unless you mean to disconnect (no auto-warning, breaks immediately)

• Audit token health monthly — admins should review the Meta users list for stale tokens

Related

• Connect your Meta account — the initial OAuth flow

• Meta connection troubleshooting — broader issue list

• Security best practices — token + OAuth security context