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

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

  • The system user must have installed the app passed in the parameter, as seen in the step above.
  • Apps can only target businesses (or child businesses of those businesses) that have claimed them.
  • 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 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"
}