Meta Ads onboarding

This walkthrough connects a Meta (Facebook/Instagram) ad account to Adsidian so the dashboard can import and manage campaigns, ad sets, and ads — and keep metrics synced hourly.

Two separate Meta connections

This page covers ads management (the Marketing API). Server-side conversion tracking is a separate, much simpler connection — see Meta (Facebook) CAPI. You'll usually want both.

How the connection works

Every Meta ads connection is two parts: a Meta app and a system-user token.

The app is always Adsidian's — you don't create or maintain a Meta developer app, and Adsidian sets the App ID and Secret on your account for you. You grant your Business Portfolio access to that app once, and from then on your system users can mint tokens against it.

Everything else stays yours. The system user lives in a Business Portfolio you control, and the ad accounts, Pages, and pixels assigned to it are assigned by you. Adsidian never holds your assets; you never hold the app secret.

Business Portfolio = Business Manager

Meta renamed Business Manager to Business Portfolio. The two names refer to the same thing, and both still appear in Meta's own interface.

Which setup are you?

Agencies structure Meta access in three ways. They behave identically once connected — the difference is where the system user lives and how many tokens Adsidian holds.

	Where assets live	Where the system user lives	Tokens in Adsidian
1. You own everything	Your portfolio	Your portfolio	One, agency-wide
2. You own some, clients share the rest	Yours + partner-shared in	Your portfolio	One, agency-wide
3. You work inside the client's portfolio	The client's portfolio	The client's portfolio	One per client

Setups 1 and 2 are the same connection — setup 2 just adds a sharing step per client, and the token never changes. Setup 3 is the one that needs its own token per client.

You can mix them. Most agencies end up with some clients on partner sharing and one or two who insist on keeping everything in their own portfolio. Adsidian resolves credentials per client, so a client with their own token uses it and everyone else falls back to your agency token — no separate workspace, no duplicate setup.

If you're starting fresh, aim for setup 2: one system user, one token, and onboarding a client is an asset assignment rather than a new connection.

---

Setup 1 & 2 — one agency connection

1. Request app access for your portfolio

In Adsidian, open Settings → Meta. The first card asks for your Business Portfolio ID (Business Settings → Business info — numbers only). Paste it and click Request access.

Adsidian grants that portfolio access to the Adsidian app so your system user can generate tokens against it. The card tracks it:

• Awaiting Adsidian — requested; we've been notified
• Granted — done, go generate your token

The grant is a manual step on our side (Meta provides no API for it), but you don't need to chase anyone — the card confirms itself against Meta and updates when access lands. Until it says Granted, the Adsidian app won't appear in Meta's token dialog.

Already granted?

Submitting a portfolio that already has access comes back Granted immediately, so it's safe to submit if you're unsure.

2. Create a system user

In your Business Settings → System users, click Add and create one (Admin role is simplest). Name it something recognisable like Adsidian Integration.

One system user is enough for your entire client roster. You do not need one per client, per Page, or per ad account.

3. Bring in client assets you don't own — setup 2 only

Skip this if every ad account and Page is already in your portfolio.

For assets owned by a client's portfolio, the client shares them with you:

1. In the client's Business Settings → Partners → Add Partner, they enter your Business Portfolio ID.
2. They assign the ad account (Manage campaigns), the Page (Manage Page), and the pixel/dataset (Manage).

The reverse direction also works: you request access from Business Settings → Accounts → Ad accounts (or Pages) → Add → Request access, and the client approves.

The step everyone misses

Sharing an asset puts it in your portfolio. It does not give your system user access to it. You still have to assign it in step 4 — that's two steps, not one, and skipping the second produces permission errors on that client only.

4. Assign your assets to the system user

On the system user, click the three dots (…) next to Revoke token → Assign assets, and grant:

• each ad account Adsidian should manage — with Manage campaigns (full control),
• each Facebook Page those ads run under — with Manage Page,
• each pixel/dataset — with Manage.

TIP

Page access comes from this assignment, not from a token permission. If a Page isn't assigned here, it won't appear in the dashboard's Page dropdown no matter what the token can do.

5. Generate the token

Click Generate new token and select the Adsidian app from the dropdown (if it isn't listed, step 1 hasn't completed). Choose no expiry, and check these permissions:

• ads_management — read and write campaigns, ad sets, and ads
• ads_read — metrics and insights
• business_management — resolve the businesses that own the assets
• leads_retrieval — read lead form submissions
• pages_read_engagement, pages_manage_metadata, pages_manage_ads — Page access for ad creation and lead forms

Copy the token. Meta shows it only once.

WARNING

The token must be a user or system-user token. A plain app token (app_id|app_secret) cannot list ad accounts or manage campaigns, and the connection test will fail with a clear error saying so.

6. Send the token to Adsidian

Because the App ID and App Secret belong to Adsidian's app, Adsidian sets those two fields on your account — you only supply the token. It's entered under Settings → Meta, where secrets are write-only: after saving, the token shows as a masked value (••••1234). To rotate it later, paste the new value; blank fields are left unchanged, and credential changes are audit-logged.

7. Test, then import

Click Test Connection. Adsidian validates the credentials live against the Graph API:

• Connected — the Ad Account and Page fields become dropdowns of everything the token can reach. Pick the right ones and Save.
• Invalid — the error says what failed (expired token, missing permission, unassigned asset).

A preview card then loads for each connected ad account showing the campaigns, ad sets, and ads that would be imported — nothing is written yet. Run the import from each card; it brings campaigns, ad sets, and ads (in that order — each level needs its parent) with their current status, budgets, and settings.

After the initial import, Adsidian syncs every account hourly. Changes made in Adsidian are pushed to Meta automatically — records show a sync status (pending → synced) so you can see exactly what's live.

Adding a client later

This is the payoff of setups 1 and 2 — onboarding client #7 is not a new connection:

1. Share the assets in (setup 2 only) — step 3 above.
2. Assign them to your existing system user — step 4 above.
3. Point the client at their ad account — on the client's record in Adsidian, set their Meta ad account ID and Page ID.

No new system user. No new token. Nothing changes in Settings → Meta.

TIP

If the token was generated before the new assets were assigned, it still covers them — Meta evaluates a system user's access at call time, not at mint time. You only need a fresh token if you changed the permission scopes.

---

Setup 3 — a system user inside the client's portfolio

Some clients won't share assets out of their portfolio, and some agencies prefer to work inside the client's portfolio so access ends cleanly when the relationship does. In that case the system user lives in the client's portfolio and Adsidian stores that token against that client.

1. Request app access for the client's portfolio

Same as step 1 above, but for the client's Business Portfolio ID — each portfolio that mints a token needs its own grant. Request it from the client's Meta connection card: choose Use a system user in the client's portfolio and the request field appears there, tracking the same Awaiting → Granted states.

2. Create a system user in the client's portfolio

In the client's Business Settings → System users, add one (Admin role is simplest) and name it recognisably, e.g. Adsidian Integration.

You need admin access to the client's portfolio to do this. If the client would rather do it themselves, send them steps 2–4 of this section and ask for the resulting token.

3. Assign the client's assets to it

Ad account (Manage campaigns), Page (Manage Page), pixel/dataset (Manage) — exactly as in setup 1/2 step 4. No partner sharing is involved: the assets and the system user are already in the same portfolio.

4. Generate the token

Generate new token → select the Adsidian app → no expiry → the same permissions listed in setup 1/2 step 5.

5. Save it on the client record in Adsidian

Open the client in Adsidian → Meta connection → choose Use a system user in the client's portfolio, paste the token, and Save. Adsidian verifies it immediately and shows which ad accounts it can reach.

That client now syncs, mutates, and pulls leads on their own token; every other client continues on your agency connection. Test connection on the card re-checks it any time, and a token that starts failing is flagged on that client rather than reported as a workspace-wide outage.

One token, not two

Prism's server-side conversion tracking uses the same token automatically — when you set up CAPI for this client, keep the default "no token to paste" option. You only paste a dataset-specific token there if you deliberately want CAPI on a different connection than ads management.

To hand a client back to the agency connection later, choose Use the agency connection — the stored token is deleted and resolution falls back immediately.

---

Multiple clients, multiple ad accounts

The Ad Account ID in Settings → Meta is the agency fallback. Each client can override it with their own Meta ad account ID on their client record, and the connection test previews every configured account (fallback plus each client override) so one test confirms access to all of them.

Which token each account syncs on is resolved per client:

• client has their own token (setup 3) → that token,
• otherwise → your agency token.

This is why a mixed roster works without splitting your workspace.

Troubleshooting

Symptom	Likely cause / fix
"requires a User or System User access token"	You're using an app token. Generate a system-user token.
Token was valid, now Invalid	User tokens expire (~60 days) and die on password changes. Use a system-user token — those don't expire.
Permission error (#200) / (#10) on an account	The system user isn't assigned that ad account or Page. Sharing an asset into a portfolio is not the same as assigning it — check Assign assets.
One client fails, everyone else is fine	Asset-level problem for that client: partner share revoked, asset unassigned, or (setup 3) their token was rotated. Their campaigns keep running; only the sync breaks.
Every client fails at once	Token-level problem: your agency token was revoked, or the system user lost its role.
(#200) API access blocked. on every call, before any account is named	Meta has restricted the app. Adsidian owns the app and handles the appeal — contact your Adsidian representative rather than changing anything on your side.
The Adsidian app isn't in the Generate new token dropdown	That portfolio hasn't been granted access to the app yet. For setup 3, note the grant is per portfolio — the client's needs its own.
Preview works for the agency account but not a client's	The client's ad account hasn't been shared into your portfolio, or the system user isn't assigned to it.
Lead form calls fail	Token is missing pages_manage_ads / leads_retrieval, or the Page isn't assigned to the system user. Ad-account access alone is never enough for leads.
Dashboard numbers trail Ads Manager by a day	Your account is on a daily sync — ask Adsidian to switch it to hourly. Meta also credits conversions back to the click date, so recent days keep rising for up to a week in both systems.
Rate-limit errors	Adsidian backs off and retries automatically; large imports may take a few minutes.

Next

• Set up server-side conversion tracking: Meta (Facebook) CAPI
• Connect Google Ads: Google Ads