Facebook Login

Facebook Login for Business

Facebook Login for Business is the preferred authentication and authorization solution for Tech Providers and business app developers who need access to their business clients' assets. It is an alternative to Facebook Login. If you are not a Tech Provider, or you are not building a business app for use by other businesses, use Facebook Login as your authentication solution instead.

Benefits

Compared to Facebook Login, Facebook Login for Business allows you to specify the access token type, types of assets, and permissions your app needs, and save it as a set (configuration). You can then present the set to your business clients who can complete the flow and grant your app access to their business assets. It removes the ability for a business to grant you permission to certain categories of information that are typically not necessary for a business app. It allows you to choose between different access tokens based on your apps’ needs.

Supported Permissions

You may request the following permissions from your business clients. Note that unlike Facebook Login, Facebook Login for Business requires your business client to grant all of the permissions that you specify in your configuration.

The email and public_profile permissions are automatically granted to all apps. However, they must be used with at least one other supported permission for each app installation.

The public_profile permission is automatically granted to all apps however it will not be returned in the scope parameter unless at least one other supported permission, excluding email, is granted by an app user.

Available PermissionsUser access tokensBusiness Integration System User access tokens

ads_management

✓

✓

ads_read

✓

✓

business_management

✓

✓

catalog_management

✓

✓

email *

✓

N/A

instagram_basic

✓

✓

instagram_content_publish

✓

✓

instagram_manage_comments

✓

✓

instagram_manage_insights

✓

✓

instagram_manage_messages

✓

✓

instagram_shopping_tag_products

✓

✓

leads_retrieval

✓

✓

manage_fundraisers

✓

✓

pages_manage_cta

✓

✓

page_events

✓

✓

pages_manage_ads

✓

✓

pages_manage_engagement

✓

✓

pages_manage_instant_articles

✓

✓

pages_manage_metadata

✓

✓

pages_manage_posts

✓

✓

pages_messaging

✓

✓

pages_read_engagement

✓

✓

pages_read_user_content

✓

✓

pages_show_list

✓

✓

private_computation_access

✓

✓

public_profile *

✓

N/A

publish_video

✓

✓

read_insights

✓

✓

read_audience_network_insights

✓

✓

whatsapp_business_management

✓

✓

whatsapp_business_messaging

✓

✓

Available Features

Available Products

Supported Access Tokens

You can use Facebook Login for Business to get either Business Integration System User access tokens or User access tokens. Note that your current access tokens will not be impacted upon switching to Facebook Login for Business.

Business Integration System User Access Tokens

Business Integration User access tokens are generated by Facebook Login for Business and should be used if your app performs programmatic, automated actions on your business clients' Ad objects or Pages without having to rely on input from an app user, or require re-authentication at a future date. For example:

  • Hourly, automated server-to-server conversion API calls
  • Sending automated responses as a Page.
  • Continuous, automated updates to product catalog inventories.
  • Automated retrieval of ads insights.

In order to be able to get Business Integration User access tokens from your business clients:

  • Your app cannot request logins from mobile surfaces (i.e Android, iOS, etc).
  • The business client completing the Facebook Login for Business flow must have, or be willing to create, a Meta Business Account.
  • Your app must be associated with a Meta Business Account which you have full control. This needs to be separate from the Meta Business Account owned by your business client.
  • The Business Integration System User access token is created/updated and sent to you when an end user finishes app installation

To test the Business Integration System User access token flow, the tester must have a role on the app.

Difference between Business Integration System User and regular System User

  • The regular System User is an independent product representing servers or software making API calls to assets owned or managed by a Business Manager; it can only be accessed by the business users within the same business.
  • Business Integration System User must be part of the Tech Provider integration's infrastructure, initialized by client business through Tech Provider’s App installation such as Facebook Login for Business’s System User Access Token flow, and be accessed by the Tech Providers only.
  • Business Integration System User access tokens cannot be invalided via the System User tab in the Business Manager. Instead, your business clients must go to the Business Manager > Business Settings > Integrations > Connected Apps tab and click the Remove app button to uninstall your app, which will invalidate the tokens.

Granular Business Integration System User Access Tokens

For certain Tech Providers, typically larger organizations, who might need different access setups for different purposes or departments instead of using the one Business Integration System User access token per client business, multiple granular Business Integration System User access tokens per client business are available to improve the scalability/security of your operations.

  • Granular access tokens are still specific to a client business’ business. They are not shareable and accessible across different client businesses.
  • Granular access tokens’ scope and asset list should be a subset of the original Business Integration System User access token.
  • In the event of a compromised token, only that specific client business will be impacted, instead of impacting all Business Accounts across all client businesses. This helps isolate potential security incidents and decouples interdependencies between Business Accounts and/or client businesses.

Business Integration System User Access Token Management API

This endpoint allows developers to manage their existing system user access token by the following:

  • Generate more granular system user access tokens from the existing Business Integration System User access token
  • Fetch existing Business Integration System User access token (both the original one or the more granular ones)
Parameters:
ObjectDescription

Client business id

int

Required.

When an end user installs an app through the Facebook Login For Business flow which generates system user access token at the end, such token will be scope in the selected business by the client. Client business id is the id of one of these businesses

Appsecret_proof

string

Required.

Since this is a token management API, we require Appsecret_proof a sha256 hash of your access token to make sure the calls from a server are better secured. See more details here.

Access_token

string

Required.

Access_token requires manage_business permission.

system_user_id

int

Optional.

The system_user_id is the id for the system user within the access token.

fetch_only

bool

Optional.

fetch_only is the flag you want to use to fetch the existing token and indicate this operation is read only

asset

int

Optional.

When you want to generate a more granular token, you can set a list of asset ids, separated by commas. The list of assets will have to be a subset of assets from the original access token.

scope

bool

Optional.

When you want to generate a more granular token, you can set a list of scope ids, separated by a comma. The list of assets will have to be a subset of scopes from the original access token.

set_token_expires_in_60_days

bool

Optional.

When you want to generate a new token, you can make the token expire in 60 days

Sample Request
curl -i -X POST \ 
  'https://graph.intern.facebook.com/v17.0/2738613836382965/system_user_access_tokens?appsecret_proof=<app_secret_proof_sanitized>&
access_token=<access token sanitized>&   
system_user_id={system_user_id}&
fetch_only=true'
Sample Response
{
  "access_token": "{access_token}" 
}

User Access Tokens

User access tokens should be used if your app takes actions in real time, based on input from the user. For example, use a User access token if your app requires a user to input text and click a button in order to post content to their page. User access tokens should also be used if you require an API that requires admin permissions on a Meta Business Account.

Comparison

System User access tokensUser access tokens

Account association

Associated with your business client's business account rather than a specific user. Any admin in your business client's admin group can grant your app a System User access token.

Associated with your app user's personal account.

OAuth grant type

Authorization Code only.

Implicit by default. Mainly used for user-agent based clients such as web browsers and mobile apps.

Expiration and refresh

Defaults to never expire for the common offline server-to-server communication.

A short-lived token for online activities such as web browsers.

Access Designations

Access is explicitly delegated at the time of authorization. Your app can only access the assets that were designated by your business client when they completed the Facebook Login for Business flow.

Access is inherited from your app user's current account access; you can access the same business assets that the app user currently has access to.

Client Invalidating Access Tokens

Your business clients can invalidate Business Integration System User access tokens by going to Business Manager > Settings > Business Settings > Integrations > Connected apps and removing your app.

For User access tokens, your business clients can remove the app by going to Facebook and navigating to Settings & privacy > Settings > Security and login > Business Integrations and removing your app.

App Installer/Login flow Experience

User access token login flowBusiness Integration User access token login flow
Something Went Wrong
We're having trouble playing this video.
Learn more
Something Went Wrong
We're having trouble playing this video.
Learn more

Getting Started

To test out Facebook Login for Business, you need to create a Business Type testing app where the Facebook Login for Business is installed automatically.

Create a Configuration

A configuration is a grouping of the token type, business assets, and permissions your app requires from business clients. This grouping will be presented to users as part of the authentication and authorization flow when they install your app. You can create multiple configurations and present them to different sets of users, depending on your app's needs. To create a configuration you will:

  1. Load your app in the App Dashboard
  2. Add the Facebook Login for Business product
  3. Click Configurations
  4. Click + Create Configuration
  5. Name your configuration
  6. Choose the type of access token you want to request from your business clients
  7. If you chose System User Access Token then select the assets your app needs access to
  8. Select the permissions your app needs
  9. Click Create

Creating a configuration will generate a configuration ID, which you can then use with our SDKs (or manually).

App Dashboard configuration for a Business Integration System User access token:

Something Went Wrong
We're having trouble playing this video.
Learn more

Create a WhatsApp Embedded Signup configuration

WhatApp Embedded Signup is exclusively accessible for Business Solution Providers (BSPs) only.

  1. Load your app in the App Dashboard
  2. Add the Facebook Login for Business product
  3. Click Configurations
  4. Click + Create Configuration
  5. Name your configuration
  6. Choose WhatsApp Embedded Signup, which will enable your app’s onboarding to WhatsApp Embedded Signup. For WhatsApp Embedded Signup, only System User Access Token is available for use
  7. Choose token expiration. We recommend choosing 60 days. It helps minimize the risk of a leaked token and enhances the security of your system.
  8. Choose the assets your app needs access to. This step is only available if you chose System User Access Token in the previous step, and WhatsApp accounts cannot be deselected
  9. Select the following permissions for your app: whatsapp_business_management and whatsapp_business_messaging
  10. Click Create

Create a IG configuration

The flow is optimized for Instagram Graph APIusage only.

  1. Load your app in the App Dashboard
  2. Add the Facebook Login for Business product
  3. Click Configurations
  4. Click + Create Configuration
  5. Name your configuration
  6. Choose Instagram Graph API, which will enable your app’s onboarding to an [Instagram specific login flow] (https://developers.facebook.com/docs/instagram/business-login-for-instagram/). Only User Access Token is available for use.
  7. Select the following permissions for your app
  8. Click Create

Invoke a Login Dialog

You can invoke the Facebook Login for Business login dialog using our SDKs, or you can invoke the login dialog by manually building the login flow.

Invoking with our SDKS

You can use any of our SDKs to invoke the login dialog by replacing the list of scopes (permissions) your app needs with your configuration ID and the access token's required OAuth grant type.

If you are unfamiliar with our SDKs, we recommend that you first install the JavaScript SDK and get it working with the consumer Facebook Login product before proceeding, as the following examples reference the SDK.

Business Integration System User Access Token Configurations

Here's an example of the JavaScript SDK's FB.login() method modified to use a configuration for a System User access token. Note that config_id has replaced scope (which should not be used), the response_type has been set to code, since SUAT's require the authorization code grant type, and override_default_response_type must be set to true. When true, any response types passed in the response_type will take precedence over the default types.

FB.login(
  function(response) [
    console.log(response);
  ],
  [
    config_id: '<CONFIG_ID>',
    response_type: 'code',
    override_default_response_type: true
  ]
);

When the user completes the login dialog flow we will redirect the user to your redirect URL and include a code. You must then exchange this code for an access token by performing a server-to-server call to our servers.

GET https://graph.facebook.com/v18.0/oauth/access_token?
  client_id=<APP_ID>
  &client_secret=<APP_SECRET>
  &code=<CODE>

See Exchanging Code for an Access Token for more information about this step.

User Access Token Configurations

Here's an example of the JavaScript SDK's FB.login() method modified to use a configuration for a User access token. Note that config_id has replaced scope (although scope can still be included, we recommend that you do not use it).

FB.login(
  function(response) {
    console.log(response);
  },
  {
    config_id: '<CONFIG_ID>' // configuration ID goes here
  }
);

Here's an example of the JavaScript SDK's login button modified to use a User access token configuration:

<fb:login-button config_id="<CONFIG_ID>" onlogin="checkLoginState();">
</fb:login-button>

Invoking Manually

See Manually Building the Login Flow to learn how to invoke the login dialog manually. When invoking the login dialog and setting the redirect URL, include your configuration ID as an optional parameter (although scope can still be included, we recommend that you do not use it).

config_id=<CONFIG_ID>

Troubleshooting

App installers might encounter error messages for the following reasons:

  • Config ID is invalid
  • System User Access Token is not currently supported on Mobile devices
  • System User Access Token is set up with incorrect response_type

Potential breaking changes:

  • If your app type is currently “None”, switching to Facebook Login for Business will lead to your app’s type changing to “Business” type; and can only access permissions, features and products available by this login product.
  • If your existing app installers only have access to email or public_profile permissions, switching the app to Facebook Login for Business will lead to the invalidation of all these previous installed tokens.
  • If your existing app installers have access to permissions/features unsupported by Facebook Login for Business, those permissions/features will be revoked immediately once the app is switched to Facebook Login for Business.
  • If your app has both Facebook Login for Business and Meta Business Extension products, the Meta Business Extension experience will be limited to permissions supported by Facebook Login for Business only.

Switch to Facebook Login

If your app is not functioning as intended after switching to Facebook Login for Business, you can uninstall it by rolling back to Facebook Login by going to the App Dashboard > Facebook Login for Business > Settings and clicking the Switch to Facebook Login link. You will be presented with a survey which helps us improve the Facebook Login for Business configuration experience. Each app is allowed to roll back to Facebook Login within 30 days after the switch and can only roll-back max three times.