Generate a Meta token
openreport reads your Meta ad data using a token you generate yourself. The whole flow takes about two minutes the first time. Read the permissions section first. Granting too much access is the only meaningful way you can put yourself at risk with this tool.
Permissions: only grant ads_read
openreport only reads your ad data. It cannot pause campaigns, change budgets, or create ads.
When you generate a token, grant ads_read only. Never grant ads_management or any write permission. If you do, a leaked token would let an attacker modify your campaigns. Stick to read-only.
Two kinds of tokens
Pick one based on how often you plan to use openreport:
The User Access Token is safer because the risk window is small. Start there. Switch to System User only when you're using the tool weekly or biweekly.
Option A: User Access Token (easiest)
The fastest path. Token expires in 1 to 2 hours.
- Go to Meta Graph API Explorer.
- In the "Meta App" dropdown (top right), pick any app you have access to. If you don't have one, create a basic app in the Meta App Dashboard — no app review needed for
ads_read. - Click Generate Access Token.
- In the permissions dialog, grant
ads_readonly. Uncheck everything else if it's pre-selected. - Copy the token. It looks like
EAAGm0PX4ZCpsBA…. - Paste it into the connect page.
When the token expires, repeat the steps to generate a fresh one.
Option B: System User Token (recommended for regular use)
System User tokens don't expire. You generate them once per ad account.
- Go to Meta Business Manager → Business Settings.
- Users → System Users. Click Add and create a system user (e.g. "Reporting User"). Role: Employee.
- Assign Assets → assign the ad accounts you want to report on. Permission: View.
- Click your system user → Generate New Token.
- Pick the app you want the token associated with.
- Permissions: select
ads_readonly. Nothing else. - Click Generate Token. Copy it.
- Paste into openreport.
The token persists across sessions. Store it somewhere safe (a password manager).
Business Manager assignment
The #1 source of "why isn't it working".
Even with a valid token and ads_read permission, the user generating the token must be assigned to the ad account in Business Manager.
Symptoms: token validates, but openreport shows "zero ad accounts" on the picker screen.
Fix:
- Go to Business Settings → Ad Accounts.
- Click the account → Add People (or Add System Users).
- Add the user that owns the token. Permission: View is enough for openreport.
Wait a minute, refresh openreport, try again.
Troubleshooting
Empty account list / zero ad accounts accessible
The token is valid but has no ad accounts assigned. See the Business Manager assignment section above.
Invalid OAuth access token (HTTP 190)
The token has expired (User Access Tokens last only 1–2 hours) or was revoked. Generate a fresh one.
User does not have permission to perform this action
You're trying to read an account you don't have access to in Business Manager. Either request access from the account owner, or pick a different account.
Application request limit reached (HTTP 17)
Meta's rate limit. openreport retries automatically with exponential backoff (up to 3 attempts). If you keep hitting it, wait a minute and try a smaller date range.
The dashboard is empty even though I have campaigns
Check the date range. By default openreport loads the last 14 days. If your account ran zero ads in that period, every KPI tile reads zero. Switch to 30d or 90d.
Revoking access when you stop
When you're done using the tool, revoke the token. Takes 10 seconds.
- Go to Meta Business Settings → Business Integrations.
- Find the app you used to generate the token.
- Click Remove.
Or, for a System User token: Business Settings → System Users → click the user → Delete or revoke the specific token.