Business Manager System User

Make programatic, automated actions on ad objects or Pages, or do programmatic ads buying. System users represent servers or software making API calls to assets owned or managed by a Business Manager. The easiest, quickest way to create a System User is in the Business Manager tool, see Ads Help Center, How do I add a new System User.

To take actions for a person managing an ad account, you should take them through the standard Facebook oAuth flow and get a user access token. If you try to use system user tokens to work on ad objects or Pages on behalf of a real user of your software, you cannot link this user to those actions unless you take them through Facebook Login.

Your Business Manager must:

  • Have a real person as an admin user.
  • Own a Facebook app. You should claim the app and associate it with a business via API or in Business Manager.

Facebook limits the number of system users per business manager based on your app's access level.

This bash script sample shows API calls which create a system user token then use it token to make Marketing API calls.

Types of System Users

There are two types of system users: admin system user and system user.

  • An admin system user can create system users, ad accounts, assign permissions, and more.
  • System user can only access the assets they have permission for.

You should create one system user for each type of access you need. You should also use the admin system user to programmatically maintain the right roles so if a system user token is compromised, it has limited scope and cannot compromise more permissions. Give system users access to assets and use system users for most API calls. You should limit using admin system user for administrative actions such as assigning permission. Since it has the most permissions, you should carefully safeguard the admin system user token.

Here is how it works:

Note these requirements and actions required to get access to business assets:

  • Your Business - We represent your business as an instance of a Business Manager in Marketing API. Your Business Manager must claim, create or share a Facebook app built on Marketing API. This app must have Standard Access or must be on a whitelist which enables it to create a system user access token.
  • Assets - These are assets that belong to your Business Manager, such as pages, ad accounts, and so on.
  • Admin User - All instances of Business Manager have an admin user. Typically this user is the same person who originally created the Business Manager object and manages it over time.
  • Admin System User - An admin user can create this special type of user who can create new users and access all assets belonging to the business.
  • System User - An admin or admin system user can create a system user. This person can ultimately access assets. You should use this type of user to manage a business' assets. While you could also do so through an admin system user we do not recommend it since that user type has more power; you should imit use of admin system users to creating other system users, and not use it for access to assets.
  • Permissions to Access - A system user must grant their user permission to access assets owned by a business.
  • System User Access Token - You need an app on Marketing API with the standard access or your app must be on a whitelist. With a system user and this app, you can generate a system user access token. After you have this token, and after a system user grants user permissions to access assets, your can access those assets programmatically.

Create System Users

If this is the first time you create a system user, you do not yet have a admin system user token. Start by getting yourself a real admin user's access token in Business Manager.

Use your admin system user token or your own admin user's access token to create a system user.

Here are the requests you need to get a system user token and make API calls. The first three steps are setup you can also do in Business Manager. When you create your first system user, you use the access token of a real user, who is an admin of the business manager.

  • Create a admin system user for your Business Manager.
  • First create an admin system user with your own admin user access token.
  • Install the app with the admin system user using the access token of the admin user.
  • Generate the admin system user token using the access token of the admin user.
  • Create a system user.
  • Create a system user using the access token of the admin user.
  • Or, create a system user using the access token of an admin system user of your business manager, if you created one.
  • Generate the access token of this system user.
  • Install the app with the system user using the access token of the admin user, or admin system user if created, or another system user if created.
  • Assign permission to assets (such as ad accounts, Pages) of this business manager to this newly created system user using the access token of the admin user or admin system user if created.
  • Generate the system user access token using the access token of the admin user, or admin system user if created.
  • Use the system user access token to make API calls on business assets.

To create a system user or admin system user via the API you need:

  • An access token: of an admin user, or admin system user for this business manager
  • Role: ADMIN or EMPLOYEE
  • Name: identifier of this system user or admin system user

To create a system user make a POST request as shown the in the below example:

curl \
-F "name=Ad Server" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/system_users"

This returns the app-scoped id of the new system user:

{
  "id" : "100000008899900"
}

This is the app-scoped ID for a system user. You should use it to make API calls, not the canonical ID in Business Manager | System Users.

Retrieve System User

To get the list of system users, including admin system users, and their app-scoped IDs, you need an admin user or admin system user access token.

Make a GET:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/system_users?access_token=<ACCESS_TOKEN>>"

This returns a list of all system users, including admin system users, owned by a Business Manager:

{
  "data": [
    {
      "id": "1000081799813",
      "name": "Reporting server"
      "assigned_ad_accounts": {
        "data": [
          {
            "id": "act_XXXXX",
            "account_id": "XXXXXXXXX",
            "role": "ADMIN",
          }
        ],
      }, 
      "assigned_pages": {
        "data": [
          {
            "id": "1750248626186", 
            "role": "INSIGHTS_ANALYST",
          }
        ],
      },
    }, 
  ]
}
}

Update System User

You can change the name of a system user or admin system user. You cannot delete a system user or admin system user, but you can invalidate all access tokens for a system user or admin system user.

curl \
-F "system_user_id=<APP_SCOPED_SYSTEM_USER_ID>" \
-F "name=FBX Server" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/system_users"

Invalidate Access Tokens

You may invalidate all access tokens of a system user by sending a DELETE request to the endpoint:

https://graph.facebook.com/<API_VERSION>/<APP_SCOPED_SYSTEM_USER_ID>/access_tokens

The response will be true if successful. After that you can generate new access tokens for this system user as above.

Installing Apps and Generating Tokens

Since system user represents server calls, it does not have Facebook login and cannot install an app or go through the Facebook oAuth flow to generate a token. You need to do this via API calls.

Installing Apps

A system user or an admin system user must install the app that will be used for generating the token. That means to allow the app to call APIs on behalf of this system user or admind system user. Both system user and app should belong to a same business manager. Only apps with Ads Management API standard access and above can be installed.

To install an app for a system user you need following things:

  • access_token: of an admin user, admin system user, or another system user if generated
  • business_app: the app ID being installed

To install an application for system user, make a POST request as shown in the example below:

curl \
-F "business_app=<APP_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<APP_SCOPED_SYSTEM_USER_ID>/applications"

This call will return a boolean result indicating installation was successful. If any of the restrictions are not met, you will see appropriate error message.

Generate an Access Token

After the system user has installed the app, it can generate a persisting access token. Again some restrictions apply here:

  • System user must have installed the app passed in the parameter, as in the step above.
  • The system user and the owner of the access token used during this token generation API call must belong to the same business manager.
  • The app can either be owned by the same business manager, or not. If not, there are some restrictions. Please refer the section below.

Here are the parameters for the API call:

  • business_app: the app owned by or proxied to business manager that system user belongs to.
  • appsecret_proof: calculated field for the app. This is required to ensure that the right server is making the API call. For more details review the Login Security doc.
  • scope: comma separated string containing extended permissions
  • access_token: business manager admin, admin or regular system user token if generated

The following are supported scopes for system users:

  • ads_management
  • ads_read
  • business_management
  • manage_notifications
  • manage_pages
  • pages_manage_cta
  • pages_manage_instant_articles
  • pages_show_list
  • publish_actions
  • publish_pages
  • read_insights
  • read_page_mailboxes
  • read_stream
  • rsvp_event

To generate an "appsecret_proof", you can use PHP code like this:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

The hashed appsecret_proof would be a string like "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

To generate a system user access token, make a POST request as shown in the example below:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "appsecret_proof=<APPSECRET_PROOF>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<APP_SCOPED_SYSTEM_USER_ID>/access_tokens"

The endpoint was previously named /{APP_SCOPED_SYSTEM_USER_ID}/ads_access_token, which still works but will be removed in v2.3.

The response will return the access token string. If any of the restrictions are not, appropriate error codes will be thrown. The response will look something likes this:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Work with an app not owned by the same BM

It is possible to obtain an access token of the system user for an app not owned by the same business manager. That app can be either not owned by any business manager, or owned by another business manager. One requirement to do this is that there must be a user who is an admin of the same business manager this system user is of, and that user needs to have access to that app. The follow steps are needed:

  1. With the Business Manager interface, obtain the system user ID. With the Developers interface, add the system user ID as a developer of the app.
  2. Get the app-scoped ID for the app by calling /{business_id}/system_users. The access token used for this call should be of a user who:
  3. Must be a developer or admin of the app;
  4. Must be an admin of the business manager which the syster user is a part of;
  5. No need to be related to the business manager which owns the app, if the app is owned by any business manager.
  6. Install the app using the app-scoped ID.
  7. Get access token using the app-scoped ID and the app secret.

You cannot add test apps in a business manager. Instead you should add the system user as a tester of that test app so that system user to work with the test app.

System User Permissions

Assign System User Roles on Ad Accounts

You need the following to make the API call:

  • user - System user id that you created
  • Role - Access type for this system user for the ad account: REPORTS_ONLY, GENERAL_USER or ADMIN.
  • access_token - of an admin user or admin system user.

To assign system user permissions to an ad account, make the following POST request:

curl \
-F "user=APP_SCOPED_SYSTEM_USER_ID" \
-F "role=ADMIN" \
-F "business=BUSINESS_ID" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/assigned_users"

Assign System User Pages Roles

You need the following to make the call:

  • user - System user id that you created
  • Role - Access type for this system user for page: MANAGER, CONTENT_CREATOR, MODERATOR, ADVERTISER, INSIGHTS_ANALYST.
  • access_token - of admin user or admin system user.

To assign system user permissions to a page, make this POST:

curl \
-F "user=APP_SCOPED_SYSTEM_USER_ID" \
-F "role=ADVERTISER" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION>/PAGE_ID/assigned_users"

Assign System User Roles on Proxied Assets

Business manager may request access to an ad account or a page owned by another business manager. Or a business can grant access to owning assets to another business. See Business Assets.

System user can have roles over these proxied assets for given roles. The idea behind this is to provide mechanism to make API calls to ad accounts or Pages that your business manager handles for your clients.

Retrieve System User Permissions

To see permissions that a system user has over assets, you need:

  • business_id - Business Manager owning this system user
  • access_token - Of user with business_management permission or an admin user

Then make this call:

curl -G \
-d "fields=email,assigned_ad_accounts,assigned_pages" \
-d "access_token=ACCESS_TOKEN" \
https://graph.facebook.com/VERSION/APP_SCOPED_SYSTEM_USER_ID

Marketing API Calls

These calls are automated calls made by a server not a human. At this point, you have everything setup to make Marketing API calls using a system user token. The way to call the Ads API end points will not change. You will just need to use the system user token instead of the old gray user token.

Example, where access_token should be the system user token.

CURL https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/stats&amp;access_token=<ACCESS_TOKEN>

Pages API Calls

These are automated calls made by a server not a human. Once the system user has the 'manage_pages' permission, the system user access token can be used to retrieve the page access token.

The API to retrieve the token is a GET request, where me refers to the system user since that is the user id from the access token.

CURL https://graph.facebook.com/<API_VERSION>/me/accounts?access_token=<ACCESS_TOKEN>

The response will look something like this:

{
  "data": [
    {
      "category": "App page", 
      "name": "Test App Page", 
      "access_token": "CAAHYqnL1lRYBAOXZAHqZCQ5gUuIId6dKxzfOovZADPZBzSq79BxvbGQWE38IMQQxhVSbdzBPb2IgfVkmXKDTQAPf6PHG8z4WZCkhj26V2cxE7bJNgyg97JwmmDwlHVsOCNgNTMEyNAvI4suafezTmthyKboe5KABA2PrSc1BEtjMMssK6b8FP2rCNjShRcZD", 
      "perms": [
        "BASIC_ADMIN"
      ], 
      "id": "17502650099664862613886"
    }
  ], 
  "paging": {
    "next": "https://graph.facebook.com/<API_VERSION>/100008179/accounts?limit=5000&amp;offset=5000&amp;__after_id=175024862613886"
  }
}

At this point, all the steps have been taken to make page calls if you use system user to programmatically manage pages. The way to call the page end points will not change.

Limits

Your app on Marketing API has a certain access level. This determines how many system users you can create for the Business Manager that owns your app:

Level System Users Admin System Users

Development

1

1

Basic

3

1

Standard

10

1

You can group ad accounts by system user in responses based on a per-client or per- read/write basis. If you manage many ad accounts, loading all in the UI may be slow.

Resources