Business On Behalf Of

The Business On Behalf Of API allows a partner to:

  • Get access to act on behalf of their client
  • Create a system user under their client's Business Manager and fetch its access token

A system user is defined as someone who may perform repetitive programmatic tasks, such as updating a product catalog, sending server-to-server events, or updating custom audiences, and so on.

In this scenario, the system user has employee access and can only access assigned (at the time of creation) assets using the admin user's access token.

The advantage of using a system user vs. a user own access token — users can churn off a business, but system user access tokens don't expire. In this approach, the client continues to be the owner of their business and allows the partner access to their Business Manager and its assets via a system user. A client has the ability to go to their Business Manager and revoke the system user or remove certain assets access to a partner programmatically.

Get Started

Before you start, we recommend that you review these requirements and information:

Business Manager for Client

If there is no Business Manager for the client, you must create one before proceeding. For instructions, see Business Manager API.

App Permissions

  • business_management
  • ads_management
  • Ads Management standard access

Access Tokens

  • PARTNER_BM: The Business Manager of the partner who should own the app.
  • USERS_ACCESS_TOKEN: The access token of the user with business_manage permissions using the app owned by the partner's Business Manager.
  • PARTNER_BM_ADMIN_SYSTEM_USER_ACCESSS_TOKEN: The access token of the admin system user in the partner's Business Manager for the app.
  • CLIENT_BM: The Business Manager of the client where the product catalog/pixel ID (and so on) is created.
  • CLIENT_BM_SU_ACCESS_TOKEN: The access token of the system user under the client's Business Manager.

Recommended Steps

Step 1

Create the On Behalf Of relationship between the partner and client's Business Manager.

This creates an relationship edge between Partners Business Manager and Merchants Business Manager. This enables the partner to be able to create a SU via the API in the next step.

Access Token Used: USERS_ACCESS_TOKEN

curl -i -X POST \
 "https://graph.facebook.com/v4.0/<PARTNER_BM_ID>/managed_businesses?existing_client_business_id=<CLIENT_BM_ID>&access_token=<USERS_ACCESS_TOKEN>"

Step 2

Fetch the access token of system user under the client's Business Manager. This installs the app in the client's Business Manager and creates a system user. The name of the system user is "{Client_Business_Manager_Name} SYSTEM USER". A client will be able to see the partners App in their Business Manager as a shared asset. (They will not have any access to the App other than at most as a test user.)

Access Token Used: PARTNER_BM_ADMIN_SYSTEM_USER_ACCESSS_TOKEN

curl -i -X POST \
 "https://graph.facebook.com/v4.0/<MERCHANTS_BM_ID>/access_token?scope=ads_management,manage_pages&app_id=<APP_ID>&access_token=<PARTNER_BM_ADMIN_SYSTEM_USER_ACCESSS_TOKEN>"

Step 3

Get the ID of the system user.

Access Token Used: CLIENT_BM_SU_ACCESS_TOKEN

curl -i -X GET \
 "https://graph.facebook.com/v4.0/me?access_token=<CLIENT_BM_SU_ACCESS_TOKEN>"

Step 4

Assign assets (page, catalog, pixel, and so on) to the system user in the client's Business Manager.

Access Token Used: USERS_ACCESS_TOKEN

curl -i -X POST \
 "https://graph.facebook.com/v4.0/<ASSET_ID(PIXEL)>/assigned_users?user=<SYSTEM_USER_ID>&tasks=EDIT%2C%20ANALYZE&business=<CLIENT_BM_ID>&access_token=<USERS_ACCESS_TOKEN>"

Step 5

Store this client's Business Manager's system user's access token in a database somewhere and use it for any repetitive tasks, such as product catalog endpoints, order management endpoints, and so on.