Business Login Authentication

Business Login (commonly known as Facebook Login) is an entry point that allows business owners to connect their business on your platform to their Facebook or Instagram profiles, using a button you place on your site.

Business Login lives on your platform's surface (usually in an internal admin panel on your site) and triggers the Business Login flow. Business owners can use this flow to associate their Facebook profiles to their business presence on your site and enable Facebook Business Extension (FBE) features.

A Business On-Behalf-Of Solution (OBO) connecting the partner and client businesses is created during FBE install. It allows the partner to get the FBE system user access token using a partner Business Manager admin system user’s credential, besides the client Business Manager admin’s credential (the current method).

Note: Business Apps can be used as an alternative to Business Login for authentication. See the documentation on how to use Business Apps.

Requirements

Your app may need to complete App Review to get the following permissions:

catalog_management — Only if your app is going to enable Catalog features. Alternatively, you can request ads_management permission if you also want to manage merchants ads on behalf of the client.
business_creative_management - If your app is a creative app utilizing draper api.

To set up the login flow, review these options:

Load Business Login via URL— Recommended if you don't intend to use the Facebook JavaScript SDK. This option requires that you link to a dynamically generated URL per business from a button on your site.
Load Business Login via Facebook SDK—The Facebook SDK provides common client-side functionality. We recommend this option for developers who are more familiar with it as it offers a more standardized approach to launching the same flow.

Load Business Login via URL

To trigger Business Login via URL, place a button on your site that opens a URL.

The Business Login URL must have these query parameters:

Field Description

Field	Description
`client_id` Type: string	Required. Meta App ID.
`display` Type: string	Required. Display type of Business Login: `popup`, `window`, or `page`.
`redirect_uri` Type: string	Required. Redirect URI that FBE redirects to after the flow is finished.
`response_type` Type: string	Required. Determines whether the Business Login response included when the redirect back to the app occurs is in URL parameters or fragments. Use `token` if you need the `access_token` appended to the Redirect URI as a URL fragment, or `code` if you prefer to get the response as a URL parameter (it has to be exchanged for an access token using API call).
`scope` Type: string	Required. Permissions or scopes are needed: `manage_business_extension`. Depending of your use case, also `ads_management` or `catalog_management`. In case of a creative app, scope should also include `business_creative_management`.
`extras` Type: string	Required. Contains the information regarding what flows and parameters the user will see during the flow. This includes `setup` and `business_config`. See supported `extra` fields.
`setup` Type: string	Required. Merchant’s Facebook setup, such as a their unique identifier (`external_business_id`) or currency of their catalog (`currency`). See supported `setup` fields.
`business_config` Type: string	Required. Object that FBE uses to configure the FBE workflow. See supported `business_config` fields.

client_id

Type: string

Required.

Meta App ID.

display

Type: string

Required.

Display type of Business Login: popup, window, or page.

redirect_uri

Type: string

Required.

Redirect URI that FBE redirects to after the flow is finished.

response_type

Type: string

Required.

Determines whether the Business Login response included when the redirect back to the app occurs is in URL parameters or fragments.

Use token if you need the access_token appended to the Redirect URI as a URL fragment, or code if you prefer to get the response as a URL parameter (it has to be exchanged for an access token using API call).

scope

Type: string

Required.

Permissions or scopes are needed: manage_business_extension.

Depending of your use case, also ads_management or catalog_management.

In case of a creative app, scope should also include business_creative_management.

extras

Type: string

Required.

Contains the information regarding what flows and parameters the user will see during the flow. This includes setup and business_config. See supported extra fields.

setup

Type: string

Required.

Merchant’s Facebook setup, such as a their unique identifier (external_business_id) or currency of their catalog (currency). See supported setup fields.

business_config

Type: string

Required.

Object that FBE uses to configure the FBE workflow. See supported business_config fields.

If your app requires dynamic redirect URIs, use the state parameter to pass back the dynamic information to your redirect URI after the Business Login flow is complete.

For details on how to format this URL and all required parameters, see the fields listed in Facebook Business Extension API Objects and Types.

In the example below, the extras query parameter is properly formatted and specifies both business_config and setup objects.

Example URL

https://facebook.com/dialog/oauth?
client_id=<FB_APP_ID>
&display=page
&redirect_uri="https://partner-site.com/redirectlanding"
&response_type=token
&scope=manage_business_extension
//   alternatively use catalog_management or ads_management
//   &scope=manage_business_extension,catalog_management,ads_management
&extras={
  "setup": {
    "external_business_id": "foo-123",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "business_vertical": "APPOINTMENTS"
  },
  "business_config": {
    "business": {
      "name": "Foo Business"
    },
    "page_cta": {
      "enabled": true,
      "cta_button_text": "Book Now",
      "cta_button_url": "https://partner-site.com/foo-business",
      "below_button_text": "Powered by FBE Partner"
    },
    "page_card": {
      "enabled": true,
      "see_all_text": "See All",
      "see_all_url": "https://partner-site.com/foo-business",
      "cta_button_text": "Book"
    },
    "ig_cta": {
      "enabled": true,
      "cta_button_text": "Book Now",
      "cta_button_url": "https://partner-site.com/foo-business"
    },
    "messenger_menu": {
      "enabled": true,
      "cta_button_text": "Book Now",
      "cta_button_url": "https://partner-site.com/foo-business"
    },
    "thread_intent": {
      "enabled": true,
      "cta_button_url": "https://partner-site.com/foo-business"
    }
  },
  "repeat": false
}

To manually build a Login flow, enter your redirect URL in the App Dashboard:

The redirect URL is a protection mechanism for FBE redirects. If the redirect from FBE does not match the domain in your app's redirect URL field, FBE will not redirect to the URL at the end of the flow.

Go to App Dashboard and choose your app.
Scroll to Add a Product and click Set Up in the Facebook Login card.
Select Settings in the left side navigation panel.
Scroll to Client OAuth Settings and enter your redirect URL in the Valid OAuth Redirect URIs field.

As with a normal Facebook Login, the end of this flow returns an access_token, which you will use to get the Pixel ID, page ID, and Instagram Business ID.

Load Business Login via Facebook SDK

Step 1. Load the Facebook JavaScript SDK

You can download the SDK and host on your platform or pull down the Facebook-hosted SDK. We recommend using the Facebook-hosted SDK.

Step 2. Attach the fbAsyncInit function to the Window object to set up the SDK settings.

Before loading the javascript SDK, the fbAsyncInit function needs to exist on the window object. The SDK will call the function to set up the proper will call window.fbAsyncInit().

This setup includes:

appId: Facebook App ID.
cookie: Enables cookies to allow the server to access this session.
xfbml: Parses social plugins on this page.
version: Tells SDK which graph API version to use (this doc was written at the time v10.0 was the latest release)

Before loading the JavaScript SDK, attach the fbAsyncInit to the window object.

Step 3. Launch FBE via the FB.login() function (also known as "Business Login").

After loading the SDK and initializing with the proper information, use the SDK to load FB.login(). The important parameters to pass to FB.login() function are:

Response callback function
Object for scope and extras field

Field	Description
`scope`	Required. Permissions or scopes needed: `manage_business_extension` and `ads_management` or `catalog_management`.
`extras`	Required. Contains the information regarding which flows and parameters the user sees during the FBE workflow. This includes `setup` and `business_config`.
`setup`	Required. Defines the merchant’s Facebook setup such as a their unique identifier (`external_business_id`) or currency of their catalog (`currency`). See supported `setup` fields.
`business_config`	Required. Object that FBE uses to configure the FBE workflow. See `business_config` supported fields.

See Facebook Business Extension API Objects and Types for details.

Example:

<script>
    window.fbAsyncInit = function() {
    //2. FB JavaScript SDK configuration and setup
        FB.init({
            appId      : '<app_id>', // FB App ID
            cookie     : true,  // enable cookies to allow the server to access the session
            xfbml      : true,  // parse social plugins on this page
            version    : 'v4.0' // uses graph api version v4.0
        });
    };

    //1. Load the JavaScript SDK asynchronously
    (function(d, s, id) {
        var js, fjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) return;
        js = d.createElement(s); js.id = id;
        js.src = "https://connect.facebook.net/en_US/sdk.js";
        fjs.parentNode.insertBefore(js, fjs);
    }(document, 'script', 'facebook-jssdk'));

     //3. Facebook login with JavaScript SDK
    function launchFBE() {
        FB.login(function (response) {
            if (response.authResponse) {
                // returns a User Access Token with scopes requested
                const accessToken = response.authResponse.accessToken;
                const message = {
                    'success':true,
                    'access_token':accessToken,
                };
                // store access token for later  
            } else {
              console.log('User cancelled login or did not fully authorize.');
            }
        }, {
            scope: 'catalog_management,manage_business_extension',
          // refer to the extras object table for details
            extras: {
                "setup":{
                  "external_business_id":"<external_business_id>",
                  "timezone":"America\/Los_Angeles",
                  "currency":"USD",
                  "business_vertical":"ECOMMERCE"
                },
                "business_config":{
                  "business":{
                     "name":"<business_name>"
                  },
                  "ig_cta": {
                    "enabled": true,
                    "cta_button_text": "Book Now",
                    "cta_button_url": "https://partner-site.com/foo-business"
                  }
                },
                "repeat":false
            }
        });
    }
</script>

Step 4. Create a button or link to launch FBE.

To load the screen, add a button or link onClick function that calls launchFBE():

<button onclick="launchFBE()"> Launch FBE Workflow </button>

Enter your redirect URL in the App Dashboard:

Go to App Dashboard and choose your app.
Scroll to Add a Product and click Set Up in the Facebook Login card.
Select Settings in the left navigation pane.
Scroll to Client OAuth Settings and in the Valid OAuth Redirect URIs field, enter your redirect URL.

Mobile

For Mobile FBE implementation, see our Mobile documentation.

Learn More

How to do a Business Apps integration
Learn about Facebook Login
View FBE API Objects and Types
Find out more about App Review and permissions
How to uninstall FBE

Business Login Authentication

Requirements

Set Up Login Flow

Load Business Login via URL

Load Business Login via Facebook SDK

Example:

Enter your redirect URL in the App Dashboard:

Mobile

Learn More