facebook api之Access Tokens之Business Manager System User

Business Manager System User：https://developers.facebook.com/docs/marketing-api/businessmanager/systemuser/

System User Token Generation

 

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

1. First create an admin system user with your own admin user access token.
2. Install the app with the admin system user using the access token of the admin user.
3. Generate the admin system user token using the access token of the admin user.

• Create a system user.

1. 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.
2. Generate the access token of this system user.
3. Installthe app with the system user using the access token of the admin user, or admin system userif created, or another system user if created.
4. 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.
5. Generate the system user access token using the access token of the admin user, or admin system user if created.
6. 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",
          }
        ],
      },
    },
  ]
}
}

　　

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

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 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 business manager.

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 to have access to that app.

Follow these steps:

• In Business Manager, get the system user ID. In developer app dashboards, add the system user ID as a developer of the app.

• 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 syster user belongs to;

  • Is not related to the business manager which owns the app, if the app is owned by any business manager.

• Install the app using the app-scoped ID.
• Get an access token using the app-scoped ID and the app secret.

You cannot add test apps to 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&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&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:

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

• Business Manager
• Business Manager Best Practices

Best Practices and FAQ

Follow these guidelines if you are a Facebook Marketing Partner or a advertiser managing ad accounts or Pages.

Depending on your responsibility, you may handle assets differently. Here is a list of the most relevant suggestions based on your role.

Managing Ads and Pages

Marketing Partner owns Ad Accounts and Pages.

• Marketing Partner app manages assets
• Marketing Partner manages assets programmatically
• Marketing Partner employees manage assets
• How to organize ad accounts and Pages
• Do not want to use personal login?

Marketing Partner owns Ad Accounts. Customer owns Pages.

• Marketing Partner owns ad accounts & customer owns Pages

Advertiser Owns Ad Accounts and Pages

• Advertiser's employees use Marketing Partner app
• Employees logs into Marketing Partner
• Do not want to use personal login?
• Marketing Partner employees manage customer assets by granted access
• Advertiser owns assets and grant access to Marketing Partner
• Organizing ad accounts and Pages
• Do not want to use personal login?
• Marketing Partner manages assets with Advertiser's usernames and passwords. Is that OK?
• Can customer's username & password be stored with Marketing Partner?
  • Marketing Partner stores customer's passwords
• How to help customers troubleshooting?
  • Marketing Partner helps customers troubleshooting

No Ad Account

Marketing Partner owns Pages.

• Marketing Partner employees manage Pages
• Marketing Partner employees manage assets
• Do not want to use personal login?
• Marketing Partner app manages Pages
• Use system user without ads

Customer owns Pages.

• Customer employees use Marketing Partner app
• Customer logs in Marketing Partner
• Do not want to use personal login?
• Marketing Partner employees manage customer Pages
• Customer owns assets and grant access to Marketing Partner
• How to organize ad accounts and Pages
• Do not want to use personal login?

Customer logs in Marketing Partner

Customer owns the assets and they login to the Marketing Partner app directly. The Marketing Partner app uses the user's token.

• There is no code change required for apps that use the user's token to take action. The customer signs in and the app gets the token that gives the app access to the user's assets just as before.
• If the customer is using a gray user, the customer will have to connect a real user to the asset, as the grey-user login will be deprecated. As long as the customer signs into the app using a user that has access to the required assets, no change on the Marketing Partner side is needed. The process of converting grey users will be done with inline product messaging reminding these gray account owners to migrate their accounts. Once the customer starts using a real user, the customer would sign into the Marketing Partner's app using their real user credentials to access their connected ad accounts and pages and the app continues to operate.
• As before, a long lived token can be requested for this user to take care of short-term unattended actions for the user.
• A customer will be more likely to have multiple ad accounts and pages connected to their real user and we recommend that your app allow the customer to choose the ad accounts and pages they want to use on Marketing Partner platform.

Customer owns assets and grant access to Marketing Partner

Customer owns the assets, they give the Marketing Partner access by adding a Marketing Partner user account or grey user directly to the assets

• The end customer sets up a business manager and approves the Marketing Partner to manage their asset establishing
• In the case of a page, the Marketing Partner can directly request permission to the asset using their BM and the client just needs to approve it, and the client doesn't need to have a BM at all.
• Once the client has given permission to the asset to the Marketing Partner's BM, the Marketing Partner admins can assign roles to their empoyees or system users as they see fit, without needing to bother the client again.
• If there is a real person manually making changes for the customer, the Marketing Partner employee should be logging in using their own Facebook login and the employee's facebook user token being used to make calls would be the employee’s. This can be done through the UI whenever needed and can be helpful when a real person needs to look at the UI of an ad account or page. this employee would access the asset through business.facebook.com.
• The Marketing Partner could assign rights to a system user to take care of programmatic access for long running programmatic operations (the preferred solution where a long lived token from the user still isnt long-lived enough)
• In some cases 3 parties are involved, such as when one agency/Marketing Partner (lets call them X) employs a 2nd agency/Marketing Partner (Y).

1. In this case X should ask the customer to authorize X's BM. It is not supported for A and B to share credentials, and it is also not possible for X to grant permissions to the customer assets to Y (only the customer can do so)
2. The simplest solution is to have the customer also approve Y to have access to the assets.
3. Where that is not possible, BM X can add one of Y's employees into X's Business Manager, and X can assign rights to that person when necessary

Marketing Partner manages assets programmatically

The Marketing Partner's own the assets, and manages them programmatically.

• Switch from using a gray user token to using a system user token. Create a Business Manager, claim in your apps, then generate a system user and assign permissions as needed. The system user token can then be used for API calls.
• The system user cannot be used for interactive login but can be assigned specific roles on assets just like a gray user. System users are built to support automated software without getting throttled.

Marketing Partner employees manage assets

The Marketing Partner's own the assets and manages them using employees.

• Add employees in the Marketing Partner's BM, and assign roles for each employee to the required assets. Much of our Agency documentation discusses this method.
• Sometimes the Marketing Partner needs to have a very large pool of employees (like a Call center) operating on ad accounts or pages owned by the Marketing Partner.
• Where possible we recommend each employee be added to the BM
• If the number of employees becomes too large, the Marketing Partner can have it's own employees authenticate directly and use a system user (scenario C) to automate actions. This requires that the Marketing Partner map these employees to the correct assets in their own systems. We limit the number of system users that each Business Manager can create as they are meant to support automation only and a 1 to 1 mapping is not supported. for 1:1 mappings, please add the user's directly as employees into the BM. This style of ‘independent authentication’ is only permissible if all people using it are employees of the Marketing Partner. Anything that interacts with the end customer they should be authenticating using the customer's Facebook credentials or by having the customer authorize the Marketing Partner's BM.

Marketing Partner stores customer's passwords

Marketing Partner manages customer ad accounts or customer’s gray ad accounts by saving / storing end customer passwords.

• This is not an approved model as customers should not be storing end customer passwords.

Marketing Partner helps customers troubleshooting

Customer owns their ad accounts and assets, but Marketing Partner employees need access for customer ad accounts for troubleshooting reasons.

• Ask the customer to authorize the Marketing Partner’s Business Manager from their page or ad account with the right level of access.
• Within the Marketing Partner’s Business Manager, any employee can now be granted up to the level of access the customer granted the Marketing Partner's Business.
• If there is a support organization, one or more Business Managers can be setup to include the right staff and achieve the desired level of isolation between employees.
• When the task is completed, the Marketing Partner can remove the ad account or page from the Marketing Partner’s Business Manager to reduce liability. Alternatively the customer can revoke access.

Marketing Partner owns ad accounts & customer owns Pages

Marketing Partner owns the ad accounts for customers, while customer owns its own Pages.

• The customer does not have to create its own Business Manager, if it has only a few Pages.
• Marketing Partner's Business Manager asks for the access to a customer Page. If the Marketing Partner user is an admin of the Page, that access would be granted immediately. Otherwise, a Page admin needs to grant it.
• Once the Marketing Partner BM can access the Page, it can assign its own users to access the Page, thus can create ads for it.

How to organize ad accounts and Pages

Marketing Partner has multiple ad accounts and customer Pages, and wants to map which assets are for which customer.

• Marketing Partner has all those ad accounts and Pages owned or accessed by the Marketing Partner BM, which can have multiple Projects created, one Project for each customer, whose ad accounts and Pages would be included in that Project. Marketing Partner users will create ads in the context of a Project, to avoid using a wrong ad account to create ads.

Do not want to use personal login?

Marketing Partner or customer employees do not want to use their personal Facebook login to access Business Manager.

• It is highly recommened for Marketing Partner or customer employees to login Facebook using their personal login, and access ad accounts or Pages use their user access tokens. That would increase work accountablility greatly. If there were many users who could login as a certain gray user, there is no way to find out who exactly used that gray user to conduct a certain activity in the past.
• If Marketing Partner or customer creates a faked Facebook user and allow multiple employees to login using that user, the accountablity issue is still not solved; and Facebook may identify that user as a spam user thus suspend it in the future.

Use system user without ads

Marketing Partner app does not have Ads Management access, but still wants to use BM system user to invoke Page APIs.

• System Users of Business Manager can be created with Ads Management apps. For those without Ads access, such as Page Marketing Partner's, to create a system user for their Business Manager requires a manual change on the Facebook side to have this Marketing Partner included in a white list. Please work with your partner manager to have this done.
• Once such a system user is created, you can generate a page only access token, which can be used to invoke Pages API.

FAQ

Q: Why use Business Manager?
A:

Facebook user accounts only have a single personal ad account. If you need additional ad accounts you should use Business Manager. Facebook no longer creates gray-accounts for anyone needing new, additional ad accounts.

Q: Do I need a Facebook Page?
A:

To set up a Business Manager you need a Facebook page that represents your business.

Q: How do I access Business Manager APIs?
A:

If your app has Marketing API access you automatically have access to all the Business Manager APIs. You need ads_management and manage_pages permissions from any clients to manage their ad accounts and pages. When you set up a Business Manager you should claim your app or add your app to your Business Manager account using the app advanced settings panel.

Q: How is our app on Marketing API associated with a Business Manager
A:

Associate an app to your business under app settings in developers.facebook.com. See App Development. Then you can use the Business Mapping API.

Q: Does our Business Manager need access to self-service accounts when clients run ads from their own accounts and use their own lines of credit?
A:

You may need to for agencies or direct brand clients. If they authorize your app, you can take actions on their behalf, including reports and stats pulls. If you need long term access, without cleints logging into your app, you should ask them to grant your Business Manager the roles you need. You can then assign that role to your own system users. Typically you need the Advertiser roles from clients.

Q. When I request Connection Objects I get both personal assets and business assets. Can I limit the response to business assets only?
A:

Yes. Pass the business_id parameter into the call with the appropriate Business ID. You can find more information about this in Connection Objects.

Q. To run app ads what do I provide in the advertiser accounts field in `app settings`?
A:

Enter the Ad Account IDs to promote your app. This grant users access to those Ad Accounts using Business Manager and other Facebook tools.

Q. Can I add more than 25 ad accounts to a user?
A:

No. Adding ad accounts to a user at AD_ACCOUNT_ID/assigned_users bypasses this limit. See Business Manager, Ad Accounts.

Credit-related Questions

Q: Can I set my ad account to get no credit for my business credit line?
A:

Disable it from getting credit in Ads Manager. There is no API support for this.

System User and Auth Token Questions

Q:What is the difference between a user and a system user?
A:

User represents real people taking an action, while a system user represents a machine taking action. Software action should be done through a system user.

Q: What permissions do I use for deferred user actions?
A:

You should use business to business permissions which are long-term or use long-live user tokens. Business permissions has the ability for one business to give another business permissions to manage their business and the assets owned by that business.

• Business permissions documented here.
• Long-lived user tokens are documented here.

Q: Is system user a real user?
A:

A system user is a machine or software taking programmatic action on behalf a business. You cannot use it Facebook, and it is associated with your Business Manager for greater security.

Q: When do I use system user admin versus system user?
A:

An admin system user has access to everything in the business and there is only one admin system user per business.

System users can have access restrictions set by the admin system user.

When you manage actual permissions for the business itself you should use the admin system user. For example use this when you grant a new employee permissions to appropriate assets.

For all other actions such as creating ads for a specific ad account, you should use system user. System users have a higher level of security because, if compromised, they can only access what they are assigned.

Q: Can I manage a multiple accounts and create campaigns and ads if the accounts are claimed with AGENCY `access_type` with one Business Manager access token?
A:

Access tokens are by user account, therefore any ad account they have general or admin access to will allow you to create campaigns, ads, and so on. This is regardless of whether the account is direct or agency.

Q: What are the rate limits for system users? Will one system user be able to replace multiple gray users for automated actions?
A:

Rate limits for System Users are grouped by ad account and not by user.

Q: Do our existing app secrets remain the same?
A:

Yes

Q: What access token do I need to create a system user?
A:

Create the system user and fetch its token using the Business Manager, under Settings | System User. You see this option if your Business owns an app that has ads-api access, or you own an app that is whitelisted by Facebook.

Q: We manage all ad accounts for clients. Can we use the system user token for ad hoc API requests?
A:

You use a user token whenever an individual person is taking an action, and the system user token for machine initiated actions.

Q: How many system users should I have?
A:

You can logically group ad accounts per system user based on your client or your read/write model.

If you have many ad accounts, loading all of them in the UI may be slow.You should create one system user for each set of 'access types' you need. And you should use the admin system user to maintain the right roles programmatically. You can be more certain that if a regular system user token is compromised, it has limited scope and cannot compromise more permissions. You should carefully safeguard your admin system user.

Q: Do system users only have the ability to manage 25 accounts?
A:

Once you attach your app to your Business Manager, you can create more than 25 ad accounts. See Business Manager API, Ad Accounts.

Q: Why claim a page as an agency? What kind of access do would grant?
A:

You can ask for access from a someone as a business owner or as an agency for the business. This enables you to target ads at people who like a third-party's page. You should use AGENCY only when you need access to another business's Page, and don't technically or legally own it.

For agency and Facebook Marketing Partners, you should get the client to authorize your business by using an agency request. You can ask for any roles for the page.

If you're advertising, you should get the "ADVERTISER" and "INSIGHTS_ANALYST" roles.

If you need to publish to the page beyond unpublished page posts, you should request additional roles.

In your Business Manager you should assign each user only one role that is appropriate with their responsibilities.

Permissions Questions

Q: Can people outside of a Business Manager be given access to reports for it's ad accounts?
A:

Yes. The Business should grant these people access to those ad accounts.

You can also grant permissions to another business with business-to-business permissions.

Once a business has permissions to the ad accounts, their admin can then give permission to it's employees up to the permission level granted.

Q: Can I pass on permissions given to my Business to another Business?
A:

You cannot relay permissions given to your Business to another Business.

Q. When someone uses [Business Manager](https://business.facebook.com) and creates new ad account, do system users automatically get permissions to handle them?
A:

No. Even though the admin system user can create ad accounts it won't automatically have access to any ad account in the business. Business admins or Admin system users have to assign roles for users or system users with Facebook tools or APIs.

Resources

• Business Manager
• Business Manager System User
• Shared Login Migration

Business Manager

Help businesses and agencies manage Facebook Pages, ad accounts and apps in one place.

Business Manager API's can help manage multiple ad account assets and permissions.

You can also automate creating ad accounts.

See Ads Help Center, Business Manager Basics.

In Business Manager you connect ads-related assets and other business assets for:

• Project and permission management
• Run campaigns on behalf of another company.
• Create ad accounts and assign credit to buy ads.

#For example, create a new Business Manager with a POST:
curl \
-F "name=Pomni Media" \
-F "vertical=ADVERTISING" \
-F "primary_page=<PAGE_ID>" \
-F "timezone_id=1" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<USER_ID>/businesses"

　

　

Prerequisites

A business needs at least one page, an admin, a business name and a valid email address.

The business name is used only for your business and any of other businesses you choose to share objects with.

　　After you create this business, you can add pages, ad-accounts, apps, offsite conversion tracking objects, and other ads-related assets that belong to a business.

To use Business Manager API, your app needs appropriate Marketing API Access Level. Your app also needs business_management extended permission, available as of 2.7.

• You cannot use ads_management or manage_pages to call Business Management API 2.7.
• If you have an existing app on 2.6 or earlier, with approval to use ads_management or manage_pages permissions, Facebook will migrate your app to this new permission and you do not need to redo permissions review.
• If you move your app to 2.7 your app should ask for the additional permission ‘business_management’ any time your app generates a new access token for new or old users.

　　　　Apps using this permission for the first time need to go through review, see Permissions.

Work with Business Managers

Create a new business manager to represent your business. 

Only create a new business manager if you are setting up a new business manager for yourself or your clients.

If you need another ad account or access to another page, you should use your existing manager and asset permissions.

Deleting a business manager is not allowed.

Requirements

To create a business, you need:

• An access token
• A Page ID
• A vertical
• An app-scoped user ID

The Page ID you provide should be the primary page of your business.

　　This page publicly represents your business on Facebook.

Whoever creates the business is a manager of this page.

If you don't have a page to represent your business on Facebook, create one.

The vertical is one of these String constants:

ADVERTISING , AUTOMOTIVE , CONSUMER_PACKAGED_GOODS , ECOMMERCE , EDUCATION , ENERGY_AND_UTILITIES , ENTERTAINMENT_AND_MEDIA , FINANCIAL_SERVICES , GAMING , GOVERNMENT_AND_POLITICS ,MARKETING , ORGANIZATIONS_AND_ASSOCIATIONS , PROFESSIONAL_SERVICES , RETAIL , TECHNOLOGY , TELECOM , TRAVEL , OTHER

#To view properties for a business, use its ID:
curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>?access_token=<ACCESS_TOKEN>"

#you can also see a list of the business managers you can access:
curl "https://graph.facebook.com/<API_VERSION>/me/businesses?access_token=<ACCESS_TOKEN>"

Response fields include:　　

Name	Description	Type
name	Name of business	string
timezone_id	ID of the business's timezone	int
primary_page	Object of the primary page associated with this Business Manager. { "category": "App page", "name": "Sample Primary Page", "id": "123456789" }	JSON object
id	ID of the Business Manager	long
update_time	Last time this Business Manager was updated	string
updated_by	Last user, by name and id, who have updated this manager	JSON object
creation_time	Time this business created	string
created_by	Username and id who created this manager	JSON object

Updating Business Managers

Update fields in the business manager using make a POST request to https://graph.facebook.com/{API_VERSION}/{BUSINESS_ID}.

#change the business name:
curl \
-F "name=My Actual Business Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

#Change the business vertical by making the following POST request:
curl \
-F "vertical=RETAIL" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

　　

You have these options:

Name	Description
name	Required; The Name of the Business
primary_page	The ID of the primary page associated with this business manager

# update the primary page by making the following POST request. The primary page has to be owned by business manager.
curl \
-F "primary_page=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

# update all of the above in one POST request:
curl \
-F "name=My Actual Business Name" \
-F "vertical=RETAIL" \
-F "primary_page=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

　　

Managing People and Roles

There are two types of roles in Business Manager:

Name	API Constant	Description
Admin	ADMIN	Can control all aspects of the business including modifying or deleting the account and adding or removing people from the employee list. Has READ and WRITEaccess to all assets that the Business Manager is connected with.
Employee	EMPLOYEE	Can see all of information in business settings and be assigned roles by business admins. Cannot make any changes, except to add Pages or ad accounts which this user is an admin of to the business. Has READ access to all assets that the Buisness Manager is connected with.

For more information about roles, see Set up catalog roles in Business Manager.

Initially the creator of the Business is the only user on the Business and is an Admin.

Invite People

To add your coworkers to your business you must invite them.

To invite someone, provide a valid email address that they have access to.

Sending requests to add employees to a business manager is limited. When you reach this limit you will get error code 17, you should resume 24 hours later.

#To invite someone as an admin, send a POST request:
curl \
-F "email=[e-mail]" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

#To invite someone as an employee, send a POST request:
curl \
-F "email=[e-mail]" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

Facebook sends an email invitation to the work email address you specified. The invitee must check the email and follow the signup process.

Once they are done, you can see them in your list of Users.

People on Business Manager

As of v2.11 we have separate endpoints to get users based on their status. Make a GET request to retrieve each group of users.

# To get all business users:
curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users?access_token=<ACCESS_TOKEN>"

#To get system users, with system-level access:
curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/system_users?access_token=<ACCESS_TOKEN>"

#To get pending users who are invited to access a business, but who have not yet accepted:
curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pending_users?access_token=<ACCESS_TOKEN>"

　　

The endpoints return either active, pending or system users for your Business. For example:

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "name": "Alpha MK",
      "email": "[e-mail]",
      "role": "EMPLOYEE",
    }
  ]
}

The results for pending users looks like this:　

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "email": "[e-mail]",
      "role": "EMPLOYEE",
      "status": "PENDING",
      "owner": {
        "id": "USER_ID",
        "name": "Generic Emporium"
      }
    }
  ]
}

Definitions for returned fields are as follows:

Name	Description	Type
id	ID of this user scoped to this Business.	long
name	Name of this user under this Business	string
business	Business Manager that this user belongs to	JSON object
first_name	First name of this user under this business	string
last_name	Last name of user under this business	string
title	Title of user under this business	string
role	The role this person has for this business. EMPLOYEE or ADMIN	string
email	Email address of user	string

Changing Roles

To change an active user's role on your Business provide the User ID for the user.

#upgrade an Employee to the Admin role, with this POST request:
curl \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

#To change someone from an Admin to the Employee role make a POST request:
curl \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

# change the role for a pending user with this POST request:
curl \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

　　

Removing Users

Remove permissions granted to someone based on membership under your business managers.

Limit access to ad accounts and pages. If the user has access to ad accounts or pages outside of your Business Manager those permissions do not change.

For example, someone may have added themselves or they have access through another business manager

#To remove an active user from your business make a DELETE call:
curl \
-X DELETE \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

#To cancel a pending user with a DELETE request:
curl \
-X DELETE \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

　　

This remove the users from your Business and removes access to your Business's assets.

Getting Connection Objects

Connection Objects are the Facebook objects (for example, pages, apps, and so on) that an administrator manages.

An administrator can be a user or business, or in the case of apps, a developer or advertiser.

The types of connection objects are:

• Pages and Places
• Events
• Apps
• Domains

See a sample queries and learn more at Connection Objects, Reference.

Business Persona

A separate working context which is distinct from someone's personal identities, and distinct from someone's other business manager contexts.

Business Personas are only supported in v2.10 of the API and earlier.

Each person has name, email and title specific to that particular Business Manager.

Although we authenticate access with someone's individual Facebook identity within each business context, Facebook does not use or display Facebook usernames, friend lists, and so on.

Fields

Name	Description	Type
id	Business persona ID, default field	long
name	Business persona name, default field	string
business	Business manager id	long
first_name	Business first Name	string
last_name	Business last Name	string
title	Business title	string
email	Business email	string
update_time	The last time this persona was updated	string
updated_by	The last user (name and id) who have updated this persona	JSON object
created_time	The time this persona was created	string
created_by	The user (name and id) who has created this persona	JSON object

When someone accepts an invitation to your Business Manager, they create a persona. They can choose how their identity displays with in a particular Business Manager.

The persona consists of a name , first_name , last_name , email and an id.

#To get all personas associated with a specific Business Manager, make a GET:
curl -G \
-d "access_token=<ACCESS_TOKEN>"\
-d "fields=business_persona"\
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

#To get a persona connected with your user account by your user access token, on a specific business manager, make this GET call:
curl -G \
-d "access_token=<ACCESS_TOKEN>"\
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_persona"

#You may modify first_name, last_name , email with this POST request:
curl \
-F "first_name=Teddy" \
-F "last_name=Bear" \
-F "email=[e-mail]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_PERSONA_ID>"

　　

If you update email you will not see this property immediately updated for the persona even if the result is success.

Facebook first sends an email with a verification link to the new email address. After the owner of this account verifies the new email, Facebook updates the persona's email address.

Projects

Organize your business assets such as ad accounts, Pages, apps, into logical groups.

Projects help you navigate your business hierarchy more easily.

You can use them across agency and client owned assets.

You can only have one label per asset.

#To create a business project you must specify the name in a POST request.
curl \
-F "name=Test label" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/businessprojects"

#You can view all the labels under the business account with a GET request:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/businessprojects"

　

Fields

Name	Description	Type
id	Business Project ID, default field	long
name	Business project Name, default field	string
business	Business id	long
update_time	The last time this Business project was updated	string
updated_by	The last user (name and id) who have updated this Business project	JSON object
created_time	The time this Business Label was created	string
created_by	The user (name and id) who has created this Business project	JSON object
adaccounts	The adaccounts under this project for this given business	JSON object
pages	The Pages under this project for this given business	JSON object
apps	The apps under this project for this given business	JSON object

　

#view the details of a project by making this GET call:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>"

#Removing a project on the business
#You can delete a project by making this DELETE call:
curl -X DELETE \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>"

　　

Page for Project

# add a Page to a project by making following POST call:
curl \
-F "page_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/pages"

#view all the Pages under a project by making following GET call:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/pages"

#remove a Page from a project by making following DELETE call:
curl -X DELETE \
-F "page_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/pages"

　　

Ad Account for Project

#add an ad account to a project by making following POST call:
curl \
-F "adaccount_id=act_<ADACCOUNT_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/adaccounts"

# view all the ad accounts under a project by making following GET call:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/adaccounts"

#remove an ad account from a project by making following DELETE call:
curl -X DELETE \
-F "adaccount_id=act_<AD_ACCOUNT_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/adaccounts"

　　

App for Project

#add an app to a project by making following POST call:
curl \
-F "app_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/apps"

#view all the apps under a project by making following GET call:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/apps"

#remove an app from a project by making following DELETE call:
curl -X DELETE \
-F "app_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/apps"

　　

Invoicing

Business Manager API enables you to view and manage credit sources associated with a business.

Business Manager Owned Normal Credit Line

For the Marketing API partners who have invoicing enabled, you can take advantage of Business Manager Owned Normal Credit Line.

Facebook Marketing Partners (FBMP) need to contact their sales rep to get your business manager setup for credit.

　　Please make sure ask for Business Manager Owned Normal Credit Line.

　　Once this is setup, you can start using the ad account creation API to start creating ad accounts.

　　Charges will be against your business manager credit line.

For the ad accounts created via the following API, we will dynamically distribute credit across accounts and update credit limits and spend to avoid hitting the credit limits.

You will also be able to see summarized credit available and the amount of credit on each ad account.

Today, we only support normal liability, sequential liability is not supported. The process for setting this up will remain unchanged.

Month-End Invoicing

Once your credit line is set up for a business and business uses this run ads, we generated month-end invoices for the business account.

To see the business invoices, you need a finance role.

• For normal administrators and employee of a business, you can assign permissions under People in Business Manager.
• For system users, you need to assign permissions with an API call:

curl "https://www.graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/finance_permissions?user=<USER_ID>&finance_permission=<FINANCE_ROLE>"

　　Where FINANCE_ROLE can be FINANCE_ANALYST or FINANCE_EDITOR.

 #retrieve invoices under this business account, send a GET request:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/?fields=business_invoices&start_date=2017-01-01&end_date=2017-04-01"

{
  "business_invoices": {
    "data": [
      {
        "id": "1659175694099710",
        "billing_period": "2017-03-01"
      },
      {
        "id": "1303851778395619",
        "billing_period": "2017-01-01"
      },
      {
        "id": "1415846861611329",
        "billing_period": "2017-02-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "249554531892085"
}

　　

#get invoice details at a campaign level with this request:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/?fields=business_invoices{billed_amount_details,billing_period,entity,id,invoice_id,payment_term,type,campaigns}&start_date=2017-01-01&end_date=2017-04-01"

{
  "business_invoices": {
    "data": [
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "387.70",
          "tax_amount": "0.00",
          "total_amount": "387.70"
        },
        "billing_period": "2017-03-01",
        "entity": "FBUS",
        "id": "1659175694099710",
        "invoice_id": "22736800",
        "liability_type": "Normal",
        "invoice_type": "Invoice",
        "payment_term": "CUSTOMER",
        "type": "Invoice",
        "campaigns": {
          "data": [
            {
              "campaign_id": "6056967798500",
              "campaign_name": "Nhận ưu đãi",
              "tags": [
                "hello2"
              ],
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "207.62",
                "tax_amount": "0.00",
                "total_amount": "207.62"
              }
            },
            {
              "campaign_id": "6056958052500",
              "campaign_name": "Nhận ưu đãi",
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "180.08",
                "tax_amount": "0.00",
                "total_amount": "180.08"
              }
              "impressions": 100,
              "clicks": 50,
              "conversions": 30
            }
          ]
        }
      },
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "382.99",
          "tax_amount": "0.00",
          "total_amount": "382.99"
        },
        ......
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "1515766328651000"
}

　　

you can also retrieve the additional invoicing fields:

• invoice_date - Date when Facebook generated the invoice
• due_date - Date the invoice is due
• payment_status - Shows whether the invoice is Paid, Unpaid, or Partially Paid
• amount_due - How much money is currently due, and outstanding, on the invoice
• download_uri - Download a PDF of the invoice at this URI

Funding Source API

#retrieve the credit card associated with a business manager, send this GET request.
curl "https://www.graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creditcards"

# retrieve the extended credit funding source associated with a business manager, send this GET request.

curl "https://www.graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/extendedcredits"

To setup a funding source for a business, go to settings section of your business on Business Manager.

Dynamic Credit Allocation

Dynamic Credit Allocation, also known as DCAF, is our credit allocation system for periodically adjusting available credit on per ad account basis.

Our automated script runs approximately every 30 minutes and takes your available credit and evenly distributes it across all your active accounts enabled for DCAF.

Available credit includes total approved credit minus total outstanding balance.

This helps manage spend at your ad account level and allocate funding for each ad account.

A business can also “inactivate” an invoiced ad account and removing the ad account from the list that needs credit assigned.

Businesses no longer need to have Facebook manage this status.

Resources

General, Marketing API related:

• Access - Access Marketing APIs
• Setup - Create an app
• Authentication - Get permissions and access tokens
• Testing - Check access, see Access and Authentication

Business Manager:

• Asset Management - Manage assets, such as ad accounts, Pages, Instagram accounts, product catalogs, and so on.
• System User APIs - Automated services make API calls to assets owned or managed by a Business Manager. This document covers system user APIs, only available to apps with Standard access level.
• Client Messaging - Guidelines for messaging clients about Business Manager and gray account deprecation
• FAQ
• Business Manager Best Practices