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). 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)
- The simplest solution is to have the customer also approve Y to have access to the assets.
- 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 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.
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.
To set up a Business Manager you need a Facebook page that represents your business.
business_management permission 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.
Facebook requires two-factor authentication using the field
BUSINESS_ID/two_factor_type on the business object to verify people from that business who want to access the API.
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.
Yes. Pass the
business_id parameter into the call with the appropriate Business ID. You can find more information about this in Connection Objects.
Enter the Ad Account IDs to promote your app. This grant users access to those Ad Accounts using Business Manager and other Facebook tools.
Disable it from getting credit in Ads Manager. There is no API support for this.
System User and Auth Token Questions
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.
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 are documented here.
Long-lived user tokens are documented here.
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.
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.
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.
Rate limits for System Users are grouped by ad account and not by user.
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.
You use a user token whenever an individual person is taking an action, and the system user token for machine initiated actions.
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.
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.
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.
You cannot relay permissions given to your Business to another Business.
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.