Meta APIs
Managing Meta Access Tokens: User, Page, and System User Tokens Explained
Token problems cause many production outages in Meta integrations. How I choose token types, store them securely, and handle expiry and revocation.
Different Meta access tokens for different jobs
- User access tokens represent a person who logged in. They are used to discover assets, such as the Pages a user manages.
- Page access tokens act on behalf of a Facebook Page, for example sending Messenger replies or managing comments.
- Instagram user tokens, from Instagram Login, act on behalf of an Instagram professional account.
- System user tokens belong to a Business Portfolio and suit server-to-server integrations, such as the WhatsApp Cloud API.
- App access tokens are used for app-level calls and must never be exposed to clients.
Most token bugs I have fixed came from using the wrong token type for a call, or storing one token type and assuming it behaves like another.
Short-lived and long-lived tokens
Tokens returned by the login flow are short-lived, usually valid for about an hour or two. The backend exchanges them for long-lived user tokens, which last around 60 days. Page tokens derived from a long-lived user token typically do not expire on a timer, but they still become invalid if the user loses access or removes the app.
I store expiry information with each token, so the system knows when a reconnect or refresh will be needed instead of discovering it from a failed request.
Exchanging and inspecting tokens
Two calls cover most needs: exchanging a short-lived token for a long-lived one, and inspecting a token's validity and scopes with the debug_token endpoint.
GET /oauth/access_token
?grant_type=fb_exchange_token
&client_id={app-id}
&client_secret={app-secret}
&fb_exchange_token={short-lived-user-token}
GET /debug_token
?input_token={token-to-inspect}
&access_token={app-id}|{app-secret}Run both calls from the backend only. The app secret must never reach a browser or mobile app.
Secure token storage
- Tokens are encrypted at rest and never sent to the frontend.
- Each token is linked to the tenant, the Meta asset, the granted permissions, and the user who connected it.
- Access to tokens is limited to the services that call Meta APIs.
- Tokens are never written to logs, error trackers, or analytics events.
- Rotating the encryption key is possible without asking users to reconnect.
Handling invalid and revoked tokens
Users change passwords, remove the app, or lose Page roles, and tokens stop working. I treat token errors as a normal state, not an exception. The integration is marked as disconnected, background jobs for that account pause, and the customer sees a clear prompt to reconnect, instead of silent failures.
When a user removes the app, the deauthorize and data deletion callbacks tell you directly. Handle both, so stored tokens are revoked and deleted promptly.
System user tokens for server integrations
For integrations that should not depend on one person's account, I use system users in Business Settings. A system user is assigned to specific assets, such as an app and a WhatsApp Business Account, and its token carries only the permissions it needs. This avoids outages when an employee leaves or changes their password. Give each system user the minimum assets and permissions, and document who can generate new tokens.
Monitoring token health
- Run a daily job that checks tokens close to expiry and tokens that recently failed.
- Alert the customer before a token expires, with a reconnect link.
- Track the share of connected accounts in an error state.
- Re-check granted scopes after reconnects, because users can decline individual permissions.
Common Meta token mistakes
- Storing the short-lived token from login and wondering why the integration stops working a few hours later.
- Using a user token to send Page messages instead of the Page access token.
- Generating a system user token from a personal admin account and sharing it across environments.
- Ignoring declined permissions after a reconnect, then failing at the first API call that needs them.
- Calling the token exchange or debug endpoint from a browser, exposing the app secret.
Multi-tenant token design
In multi-tenant products, every API call should resolve the token from the tenant and asset involved, never from a global setting. I keep a single service responsible for loading, decrypting, and refreshing tokens, so retry and error handling are consistent across webhook processing, scheduled jobs, and user actions.
Frequently asked questions
Do Page access tokens expire?
Page tokens derived from a long-lived user token typically have no fixed expiry, but they become invalid if the user loses access, changes their password, or removes the app.
Where should I store Meta tokens?
In your backend database, encrypted at rest, linked to the tenant and asset. Never in the browser, mobile storage, or logs.
How do I check which permissions a token has?
Call the debug_token endpoint from your backend. It returns validity, expiry, and granted scopes.
Should I use a system user for WhatsApp?
Yes, for server-to-server WhatsApp Cloud API integrations a system user token is usually the right choice.