Connect Meta with a token (System User)

Open Business Settings

Go to Meta Business Manager and sign in with an admin account.

Open Meta Business Settings

ℹ️ If you manage multiple businesses, check the selector at the top left and pick the right one — the business that owns the ad account.

Create a system user

A System User is a "technical user" of the business, designed specifically for integrations.

1. In the left menu, go to Users → System users.
2. Click Add.
3. Give it a recognizable name, e.g. RoyLead Sync.
4. Role: Employee — you don't need Admin. Write access comes from the assets you assign in steps 3-5, not from the role. Click Create system user.

Assign the ad accounts (with write access)

The token only sees the assets you explicitly assign to this user.

1. With the system user selected, click Assign assets.
2. Asset type: Ad accounts → select the accounts you want to connect. If you have more than one to use, select them all now: RoyLead connects them in one go.
3. In the permissions, under Partial access, turn on "Manage campaigns": that's ads_management, the permission that allows creating and launching. ("View performance" turns on by itself — it's included.)
4. Leave "Manage ad accounts" (Full control) off: it would also grant control over the account's payments and settings, which RoyLead doesn't need.
5. Click Assign assets.

⚠️ With "View performance" only, the account connects and spend flows in, but launching won't work: Meta rejects the campaign creation with a permissions error.

Assign the pixel

At launch, the ad set declares the pixel as its conversion objective, and that call is made with the token: if the token can't see the pixel, Meta answers with a permissions error.

1. Still under Assign assets, pick the asset type Datasets (older businesses call it Pixels).
2. Select the pixel you use for these campaigns.
3. Permissions: turn on "Use events dataset" (Partial access) — it explicitly says "create ads for conversions with this dataset". Leave "Manage events dataset" off.
4. Click Assign assets.

ℹ️ This is different from the CAPI token RoyLead uses to send events to Meta. Here it's only so the campaign can point at that pixel.

Assign the Facebook Page

Every Meta ad has a Page as its sender. Pages are assigned from a different section, not from the "Assign assets" dialog.

1. Left menu: Accounts → Pages.
2. Select the Page you'll use in your ads.
3. Click Assign people and pick the RoyLead Sync system user.
4. Turn on "Ads" (create and manage the Page's ads) and "Insights", then click Assign.

⚠️ If you hit a Page permissions error at launch, come back here and raise it to Full control: linking the Instagram account sometimes requires it.

Set up the app

The token is generated through an app owned by the business, and the system user must have a role on that app. If you already have an app linked to the system user, skip to Step 7.

Create the app (if you don't have one)

No Meta approval needed: the app is just the technical "container" for the token, and any business app with the Marketing API will do.

1. Go to Business settings → Accounts → Apps → Add → "Create a new app ID".

2. App name: e.g. RoyLead Sync (the contact email is already yours).

3. Use cases: leave "Create and manage ads with the Marketing API" selected (it's the first option, checked by default).

4. Business: link the app to your business portfolio, so it belongs to the right business.
5. Review the Overview and click Create app. The Marketing API is already included thanks to the use case you picked.

Link the app to the system user

Creating the app isn't enough: the system user must have a role on the app, otherwise the token's "Assign permissions" step comes up empty.

1. Go to Accounts → Apps and select your app.
2. Click Assign people.

3. Select the system user (e.g. RoyLead Sync), turn on the "Develop app" toggle and click Assign. Leave "Manage app" off.

Publish the app (required to launch)

A freshly created app is in development mode: it reads data but can't create ads. The launch stops halfway, on the creative, with "The ad creative was created by an app that is in development mode" (1885183).

1. On developers.facebook.com/apps open your app.
2. App settings → Basic, fill in the two fields Meta requires to publish: Privacy Policy URL and Category. Save.
3. In the left menu, Publish: switch the app from "Unpublished" to published.

ℹ️ This is not Meta's App Review, which you don't need: it's only the switch that takes the app out of development mode.

Generate the token

1. Go back to Users → System users, select your user and click Generate new token.
2. Select your app from the list (the one from Step 6).
3. Token expiration: Never, for a permanent connection.
4. Check these permissions:

Permission	What it's for
ads_management	create campaigns, ad sets, creatives and ads (includes reading costs)
ads_read	spend, clicks and impressions for ROI and ROAS
pages_show_list	see the Page that sends the ads
pages_read_engagement	read the Page's data (without it the launch fails with error #100)
pages_manage_ads	publish ads on behalf of the Page and link the Instagram account
business_management	discover which ad accounts are assigned to the token

5. Click Generate token and copy it right away.

⚠️ If the "Assign permissions" step shows "No permissions available", the app isn't linked to the system user: complete Step 6 and try again.

🔒 Meta shows the token only once. Losing it is no problem: generate another one and paste it into RoyLead again.

Paste the token into RoyLead

1. Open your team's Ad Accounts tab in RoyLead.
2. Click Connect account and choose "Meta · connect the whole Business Manager".
3. Paste the token and confirm.

Go to Ad Accounts ↗

RoyLead verifies the token with Meta right away, discovers every ad account assigned to that token, pulls each account's name and currency automatically and connects them. At the end it tells you how many accounts are new and how many were updated.

ℹ️ You're never asked for an account ID: if an account doesn't show up, it isn't assigned to the system user (back to Step 3).

Import your pixels into the registry

In the campaign screen, the Pixel dropdown only lists pixels tied to that ad account. A pixel added by hand in the registry isn't tied to any account, so the dropdown stays empty and the launch is blocked.

1. Open the Pixels section of RoyLead.
2. Click Import from Meta.
3. Pick the ad account you just connected and confirm.

Go to Pixels ↗

RoyLead imports that account's pixels and ties them to the connection. A manual pixel with the same ID is overwritten, not duplicated, and its CAPI token switches to the System User one.

Verify

On the connection:

• the account shows up in the list with the Connected status;
• the automatic sync runs every few hours; you can force it with the Sync button;
• after the first sync, spend and ROI appear in Analytics alongside your leads.

On the launch, in the campaign screen → Target accounts, for each account you must be able to pick:

• the sender Facebook Page (from Step 5);
• the Pixel (from Step 9), required for conversion objectives;
• the Beneficiary (EU/DSA).

Then Validate and Launch on Meta.

⚠️ From the dashboard the campaign is published active (or scheduled for the date and time you picked, in the ad account's timezone): it starts spending from launch. Only launches triggered by an agent over MCP are published paused.