← Back to guides
Integrations

Connect Meta with a token (System User)

Import spend and ROI from Facebook/Instagram without waiting for Meta app approval.

Updated on June 3, 2026

RoyLead can automatically import spend, clicks and impressions from your Facebook/Instagram ad accounts to compute ROI and ROAS alongside your leads. On top of the classic "Log in with Facebook" (OAuth), you can connect an account by pasting a token you generate yourself in your Business Manager: it works right away, with no need to wait for Meta app approval.

📌 In short: you need two things from Meta — a System User token (with the ads_read permission) and your ad account ID — to paste into RoyLead at Advertising → Connect account → "Facebook · with token". The steps below walk you through getting them.

💡 Time needed: ~10 minutes. You must be an admin of the Business Manager that owns the ad account.

🔒 The token is like a password. RoyLead stores it encrypted and never shows it again after saving. Don't share it in chats, screenshots or email.

1

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.

2

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 — read access is enough, you don't need Admin. Click Create system user.

Creating the system user
Creating the system user

3

Assign the ad account

The token only works on assets you explicitly assign to this user.

  1. With the system user selected, click Assign assets.
  2. Under Ad accounts, select the account you want to connect.
  3. In the permissions, turn on only the "View performance" toggle (under Partial access): it's the read access that ads_read needs. Leave "Manage campaigns" and "Full control" off.
  4. Click Assign assets.

Assigning the ad account with the "View performance" permission
Assigning the ad account with the "View performance" permission

⚠️ If you skip this step, connecting the account will fail with a permissions error: the token would be valid but wouldn't "see" any account.

4

Prepare the app

The token is generated through an app in the business, and the system user needs a role on that app. If you already have an app linked to the system user, skip to Step 5.

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

You don't need Meta app review: the app is just the technical "container" for the token, and any business app with the Marketing API works.

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

The "What do you want to do?" menu → Create a new app ID
The "What do you want to do?" menu → Create a new app ID

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

App details: name and email
App details: name and email

  1. Use cases: keep "Create and manage ads with the Marketing API" selected (the first option, checked by default).

Selecting the "Create and manage ads with the Marketing API" use case
Selecting the "Create and manage ads with the Marketing API" use case

  1. Business: link the app to your business portfolio so it belongs to the right business.
  2. Review the Overview and click Create app. The Marketing API is already included thanks to the chosen use case.

App overview before creation
App overview before creation

Link the app to the system user

Creating the app isn't enough: the system user needs a role on the app, otherwise the token's "Assign permissions" step stays empty.

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

The "Assign people" button on the app
The "Assign people" button on the app

  1. Select the system user roylead, turn on the "Develop app" toggle and click Assign.

Assigning the system user with the "Develop app" role
Assigning the system user with the "Develop app" role

5

Generate the token

  1. On the system user, click Generate new token.
  2. Select your app from the list (the one you prepared in Step 4).
  3. Among the permissions, check ads_read.
  4. Token expiration: you can set it to Never for a permanent connection.
  5. Click Generate token and copy it right away.

The "Generate token" window — selecting the app
The "Generate token" window — selecting the app

Token expiration set to "Never"
Token expiration set to "Never"

Selecting the ads_read permission
Selecting the ads_read permission

The "Token created" window — copy the token
The "Token created" window — copy the token

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

🔒 Meta shows the token only once. If you lose it, no problem: generate another and re-paste it into RoyLead.

6

Find the ad account ID

  1. In Business Settings, go to Accounts → Ad accounts.
  2. Select the account: the ID is the number shown (e.g. 123456789012345).

RoyLead accepts both the bare number and the act_123456789012345 format.

7

Paste everything into RoyLead

  1. Open the Advertising section in RoyLead.
  2. Click Connect account and choose Facebook · with token.
  3. Paste the token and the account ID, then confirm.

The "Connect Facebook Account" dialog in RoyLead
The "Connect Facebook Account" dialog in RoyLead

Go to Advertising ↗

RoyLead immediately validates the token with Meta, fetches the account's name and currency automatically (you don't pick it), and saves the connection.

8

Verify

  • The account appears in the list with a Connected status.
  • Automatic sync runs every few hours; you can also trigger it with the Sync button.
  • After the first sync, spend and ROI show up in Analytics alongside your leads.

Token and app: how they coexist

The manual token and "Log in with Facebook" (OAuth) are two ways to get the same thing: permission to read the account's data. You can use the token now and switch to OAuth whenever you want, without losing historical data.

ℹ️ One caveat: the token is tied to the Meta app used to generate it. If that app gets suspended by Meta, both the token and OAuth stop. The token protects you from issues with the login flow, not from an app suspension.

If the token expires or stops working

If you generate a token with an expiration and it lapses, or you revoke it from Business Manager, RoyLead flags the account with an error status.

To fix it: on the account card, ⋯ → Edit credentials, paste the new token and save. No need to redo the whole connection.

Troubleshooting

What you seeCauseFix
Invalid token or account IDWrong token or wrong account IDRecheck Step 5 and Step 6
Permissions error (#200)Missing ads_read or account not assignedStep 3 and Step 5
"No permissions available"The app isn't linked to the system userStep 4: link the app to the system user
"Account already connected"The account is already on the teamIt's already there — no need to reconnect
Error status after a few daysToken expired or revokedEdit credentials and re-paste the token
Wrong currency—Currency comes from Meta automatically and can't be changed

💡 Generate the token with a Never expiration to avoid interruptions: it's the most convenient choice for continuous sync.

Best practices

  • 🔑 Use a dedicated system user for RoyLead: revoking its token only blocks this integration.
  • 🔒 Assign the system user only the ad accounts you actually want to sync.
  • 🚨 Treat the token like a password: if you think it leaked, regenerate it in Business Manager and re-paste it.

Ready to put this into practice?

Create your RoyLead account and start in minutes.

Get started free ↗