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:

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.

Once you have your admin system user token, use it, 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_SYSTEM_USER or SYSTEM_USER
  • 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=SYSTEM_USER" \
-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": "1000080664377166", 
      "name": "Ad server"
    }, 
    {
      "id": "100008024578348", 
      "name": "Reporting server"
    }, 
  ]
}

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

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 blow.

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:
    1. Must be a developer or admin of the app;
    2. Must be an admin of the business manager which the syster user is a part of;
    3. No need to be related to the business manager which owns the app, if the app is owned by any business manager.
  3. Install the app using the app-scoped ID.
  4. Get access token using the app-scoped ID and the app secret.

As a test app cannot be added in a business manager, to add the system user as a tester of that test app is the only way to for the system user to work with that test app.

System User Permissions

Assign system user to have roles on ad accounts

You will need the following things to make the API call:

  • user: System user id that you created above
  • Role: Desired access type for this system user over the provided ad account, roles are REPORTS_ONLY, GENERAL_USER or ADMIN.
  • business: Owning business manager of this ad account and system user.
  • 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/<API_VERSION>/act_<AD_ACCOUNT_ID>/userpermissions"

Assign system user to have roles on pages

You will need the following things to make the api call:

  • user: System user id that you created above
  • Role: Desired access type for this system user over the provided page, roles are MANAGER, CONTENT_CREATOR, MODERATOR, ADVERTISER, INSIGHTS_ANALYST.
  • business: Owning business manager of this page and system user.
  • access_token: of an admin user or admin system user.

To assign system user permissions to a page, make the following POST request:

curl \
-F "user=<APP_SCOPED_SYSTEM_USER_ID>" \
-F "role=ADVERTISER" \
-F "business=<BUSINESS_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/userpermissions"

Assign system user to have 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. This is explained in Business to Business Functions of the Business Manager API doc.

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

In order see the permissions that a system user has over assets, you need following things:

  • business_id: Business manager owning this system user
  • access_token: of a user with permission business_management or an admin user.

To see the list of assets that a given system user has, call the following api.

curl -G \
-d "fields=email,adaccount_permissions,page_permissions,is_system_user" \
-d "user=<APP_SCOPED_SYSTEM_USER_ID>" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions

The result will look something like this:

{
  "data": [
    {
      "adaccount_permissions": [
        {
          "id": "act_4394608127710", 
          "role": "ADMIN", 
          "status": "ACTIVE"
        }
      ], 
      "page_permissions": [
        {
          "id": "1750248626186", 
          "role": "INSIGHTS_ANALYST", 
          "status": "ACTIVE"
        }
      ], 
      "is_system_user": true, 
      "user": {
        "id": "1000081799813", 
        "name": "Reporting server"
      }
    }, 
  ]
}

By not providing the user id, you can get the list of all user assets.

API Calls

Marketing API Calls

These API calls refer to the automated calls made by a server not a human, as pointed out in overview sections.

At this point, you have everything setup to make Marketing API calls using 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&access_token=<..>

Pages API Calls

These API calls refer to the automated calls made by a server not a human, as pointed out in overview sections.

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, which looks like this, note that me referring the system user because 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&offset=5000&__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:

LevelSystem UsersAdmin System Users

Development

1

1

Basic

3

1

Standard

10

1

You can logically group the ad accounts by system user based on per-client or per- read/write models you setup. If you manage many ad accounts, loading all of them in the UI may be slow.

Resources