Meta Business Extension

Business Apps Authentication


Business Apps, available across Facebook surfaces, is where small businesses can go to discover and connect to third-party business apps to easily get set up with business tools at low tech cost in order to grow and achieve their business goals.


Unlike Business Login, because the Business Apps flow is launched from our surfaces, there is an additional step that requires the user to log in to your platform via a pop-up browser to authenticate and select their business to connect (identified by an external_business_id defined by you). On successful authentication, the user will be redirected back to the flow to complete the onboarding.

If you would like to have your app displayed on our Business Apps surface, you need to build an authentication URL, a Webhook endpoint and get those set up and validated via Developer Panel.

All apps must apply for Integration Review, once your FBE integration is approved, your app will be available to public users.

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

Authentication URL Implementation

Business Apps launches a flow analogous to Business Login from a Facebook Page surface, Instagram, and Facebook Business Suite. To enable this flow and have your app listed there, you must provide a custom authentication UI that allows the user to select their business on your site and then redirect them back to the Facebook, Instagram, or Facebook Business Suite flow.

How It Works

  1. Provide a custom URL endpoint (authentication URL) that loads your platform’s authentication flow.
    • Your authentication URL should lead the user (business owner) to a login flow on your platform.
    • Provide an option to register a new account on your platform (i.e. "signup"). After registering, the user should be sent back to Facebook to complete connecting their account.
    • If you support multiple businesses per account on your platform, the authentication URL after a successful login should then surface a UI for the user to select which business on your platform they want to associate with their Facebook assets.
    Example — Authentication URL 
    https://yourwebsite.com/fbe-auth
  2. Facebook loads your provided authentication URL during the onboarding flow and appends a redirect_uri query parameter to the end (this is a redirect URI which may include additional query parameters): 
    https://yourwebsite.com/fbe-auth?redirect_uri=<an_encoded_redirect_uri_with_query_params>
    Example — An encoded redirect URI you might get appended in redirect_uri query parameter: 
    https://www.facebook.com/local/dev/transaction_tool_selector/redirect?app_id=<int_value>&app_name=<string_value>&page_id=<int_value>
    At the end of this step, Facebook loads your authentication URL with the appended redirect_uri query parameter encoded that might look like this: 
    https://yourwebsite.com/fbe-auth?redirect_uri=https%3A%2F%2Fwww.facebook.com%2Flocal%2Fdev%2Ftransaction_tool_selector%2Fredirect%3Fapp_id%3D123%26app_name%3DSample%26page_id%3D456

    Important Note: To ensure that you are not sharing any user data with other parties, only redirect to the redirect_uri if it matches the following regular expression:

    https?:\/\/(www\.|m\.|l\.|web\.|business\.)?(\d{4,5}\.od\.)?(business\.)?(facebook|instagram|whatsapp)\.com(\/.*)?
  3. After the user completes the login/signup and selects a business on your platform (when applicable), redirect them to the URL from redirect_uri after appending to it an encoded extras object as a query param (same as you might use for Business Login) with business_config and setup defined in it (depending on the onboarding configurations you want to implement): 
    https://www.facebook.com/local/dev/transaction_tool_selector/redirect?app_id=<int_value>&app_name=<string_value>&page_id=<int_value>&extras=<an_encoded_json_string>

Note: When providing an option to create a new account on your platform in your Authentication URL, please ensure that the UI rendered is either 1) mobile-friendly/responsive and/or 2) opens with height/width sufficient to render your partner signup flow correctly (suggested minimum dimensions: 600px by 600px).

iframe Authentication

To enable a more seamless user experience within Business Apps and better support the creation of new accounts on your platform, you should enable your authentication URL to load in an iframe on a Facebook surface. See the implementation guidelines and post-message specifications in the iframes documentation.

Webhook Implementation

Webhooks allow you to receive real-time HTTP notifications of changes to specific objects in the Facebook Social Graph. For FBE this means that after a user installs or uninstalls FBE using your app (e.g. via Business Apps), you will receive the details for that action via Webhooks.

You should build an endpoint on a secure server that can process requests from Facebook. This is required for all platform partners that want their app available on Business Apps. See the Webhook implementation guide for details about how to build this endpoint.

Webhook Setup and Validation

Once your Webhook endpoint is ready, its setup and validation require that you:

  1. Use the Webhooks card in the Facebook Business Extension -> Setup section of the App Dashboard to validate the endpoint, and subscribe to the fbe_install webhook. See the Webhook implementation guide for more details.
  2. Once the Webhooks product is correctly configured, the circle at the top right of the card should turn green and show a tick icon.

Setup and Validation via Developer Panel

The Facebook Business Extension Developer Panel is a product in your Developer App Dashboard. Once your apps are granted FBE capability, you should use the Developer Panel to set up and validate your authentication URL, Webhook endpoint and to add details about what your application offers to a business.

Authentication URL Setup and Validation

Once your authentication URL is ready, its setup and validation require that you:

  1. Go to the FBE Developer Panel in your app's dashboard. Note: If you haven't configured it, follow these instructions to add it.
  2. Click the Setup tab and look for the Business Apps surface card.
  3. Check Display my app on the Business Apps surface checkbox.
  4. In the Authentication URL input, enter your authentication URL.
  5. Click the Test Authentication button.
    • A pop-up window opens and loads your URL to mimic how Facebook will use it on Business Apps surfaces.
    • Proceed with the login and business selection (if applicable).
    • After the redirect, the pop-up window closes. If there are any errors in your implementation (e.g. invalid values on extras), they will be displayed at the bottom of this card so you will know what to fix. The Test Authentication feature will only validate input on redirect_uri, and does not actually install FBE.
  6. Once implementation steps and extras configuration is implemented as expected, you will get this step marked as valid (green check on the top right corner of the card). This will enable the ability to end-to-end test this onboarding flow (install FBE) directly from Facebook (see section below).

End-to-End Testing

Once your authentication URL and Webhook endpoint were successfully set up and validated on the Developer Panel, you can do end-to-end testing of the onboarding flow, powered by your app, before going live. This can be done directly from Facebook Business Suite or the Facebook Page surface as follows:

Via Facebook Business Suite

  1. Go to Facebook Business Suite.
  2. On the left rail, click More Tools and then click Business Apps.
  3. All the available apps are listed there. Yours will be listed under the category you selected as Vertical(s) on the Developer Panel Setup tab.
  4. Your app will have a Testing Only - Not Public label. This means it’s available for testing only for the users that have a role in your app, not public users yet.
  5. Click on Connect and start testing the experience powered by your authentication URL:
    • The onboarding flow does real FBE installs and will fire the Webhook notifications.

Via Facebook Page Surface

  1. Go to a Facebook Page you have Administrator access to.
  2. On the left rail of your Facebook Page, click Business Apps.
  3. All the available apps are listed there. Yours will be listed under the category you selected as Vertical(s) on the Developer Panel Setup tab.
  4. Your app will have a Testing Only - Not Public label. This means it’s available for testing only for the users that have a role in your app, not public users yet.
  5. Click on Connect and start testing the experience powered by your authentication URL:
    • The onboarding flow does real FBE installs and will fire the Webhook notifications.

Learn More