Install Apps and Generate Tokens

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

Install Apps

A system user or an admin system user must install the app that will be used for generating an access token. That means to allow the app to call APIs on behalf of this system user or admin 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:

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

To install an application for system user, make a POST request:

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 returns a boolean result, if installation is successful. If any of the restrictions are not met, you see an appropriate error message.

Generate Access Token

The POST /<APP_SCOPED_SYSTEM_USER_ID>/access_tokens endpoint described below is temporarily only available to apps that have queried it within the last 90 days.

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

  • System user must have installed the app passed in the parameter, as seen 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 be owned by the same Business Manager, or not. If not, there are some restrictions. See 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 Login Security.
  • scope: comma separated string containing extended permissions.
  • access_token: token belonging to Business Manager admin, admin system user or regular system user.

Supported scopes for system users:

  • ads_management
  • ads_read
  • business_management
  • manage_notifications
  • pages_manage_cta
  • pages_manage_instant_articles
  • pages_read_engagement
  • pages_manage_ads
  • pages_manage_engagement
  • pages_manage_posts
  • pages_show_list
  • pages_read_user_content
  • pages_manage_metadata
  • read_insights
  • rsvp_event

To generate an appsecret_proof, you can use PHP code:

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

In code sample above, app_secret_for_the_app_used_in_the_call refers to the app secret for the app used to generate the access token. Your app secret can be found in your App Dashboard.

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

To generate a system user access token, make a POST request:

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. A call to that name no longer works.

The response returns the access token string. If any of the restrictions are not met, appropriate error codes are thrown. The response:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Work On Apps Not Owned By Same Business Manager

You can get a system user access token for an app not owned by the same Business Manager. That app may not be owned by any Business Manager, or it is owned by another one. To do this, you should be the user who is an admin of the same Business Manager this system user belongs to. You also need access to that app. Follow these steps:

  1. In Business Manager, get the system user ID.
  2. Inside the developer app dashboards, add the system user ID as a developer of the app.
  3. Share the application to your Business Manager.
  4. Get the app-scoped ID for the app by calling /{business_id}/system_users. The access token used for this call must be for a user who is:
    • A developer or admin of the app
    • Must be an admin of the business manager which the system user belongs to
    • Is not related to the Business Manager that owns the app, if the app is owned by any Business Manager.
  5. Install the app using the app-scoped ID.
  6. Get an access token using the app-scoped ID and the app secret.

You cannot add test apps to a Business Manager. Instead, add the system user as a tester of that test app so that system user works with the test app.