Meta Work Accounts

Meta Work Accounts & Third-party Integrations

Overview

Meta Work Accounts are an account type for business tools across Meta. Organizations are able to manage these accounts with administrative features including single sign-on (SSO) support, automated account provisioning and more. With work accounts, individuals can access Meta’s business tools, such as Business Manager, with their work credentials, without needing to use their personal Facebook account.

Since work accounts are meant to be used for work only, the following are constraints within the Meta work account type:

  • Does not have a social timeline or Facebook News Feed
  • Cannot access consumer-facing products or surfaces on facebook.com, except for access to post as the Page
  • Cannot have personal asset permissions (must be through a business account)
  • Can only grant business app type permissions and cannot grant user_* related permissions, such as user_friends or user_posts. Note that Meta work accounts can still complete login flows requests, but will ignore user_* related permissions.

Third-party app integration

Businesses undergoing migration to Meta work accounts will transition users from using their Facebook accounts to using their work credentials to access Meta’s business tools. Users will be able to log into Business Manager with their work accounts instead of their Facebook accounts.

If your app is accessing clients’ business assets using System user access tokens or partner sharing, your third-party integration should not be impacted. If your app is using User access tokens (or Page access token generated from User access tokens), your app’s permissions and access to business assets granted by personal Facebook accounts will not automatically transition to the new Meta work accounts. Users will be required to regrant permissions to those business assets using their new work accounts to preserve your apps' access to those assets.

Guidelines for Tech Providers

To proactively minimize potential disruptions to your API calls, it is recommended your app provides the following:

  • Ability to proactively reauthorize an asset (e.g. page, ad account) before token invalidation. This can be done by periodically checking the user_access_expire_time field of each asset and prompting the user to reauthorize if a timestamp is returned.
  • Ability for users to bulk reauthorize assets for disconnected or soon-to-be disconnected assets. This can be done by providing a "Reconnect" or "Replace Expired Tokens" button in your application that allows users to reconnect all their business assets at once instead of one by one. The button should trigger an API call to your server with a list of business asset IDs and a new access token as parameters. Your server can then use the new access token for each of the business assets in the list and store them securely in your application's database or storage.

    • Getting started with testing

    Sandbox to validate that Meta work accounts are supported by your integrations.

    Test work accounts

    In the Test Users section of your app dashboard, we provide a way to create and manage simulated Work Accounts to test your app's implementation of Facebook Login and any permissions or features your app uses. By leveraging the Test User Tool's capabilities for creating and managing Work Account test users, you can ensure a smoother experience for users logged into Work Accounts while integrating Facebook Login functionality into your app.

    These test work accounts cannot interact with real users, and any data you generate with a test user will only be visible to other test users on your app, or to real users who have an Administrator, Developer, or Tester role on your app. You can create, edit, delete, and login as a test user only through your App Dashboard (not via Graph API).

    Limitations

    Please refer to the primary documentation for additional details on test user limitations. The same limitations for test Facebook users apply to test work accounts, except that apps are limited to 1 test work account.

    Creating test work accounts

    You can create test users in the App Dashboard by going to the Test Users section in the Roles > Test Users panel, choosing the Work Accounts tab, and clicking the Create test users button. This will open a dialog that allows you a test work account.

    The Create Test Work Accounts dialog allows you to:

    • Create a single test work account.
    • Select whether the created test work account will have the app installed by default.
    • Select the Graph API version to use in calls.
    • Grant permissions for the app for each test user.

    Once created, test users will appear in the Work Accounts table.

    Testing with work accounts

    You can test your app with a test work account by using the test work account's credentials in Facebook Login and granting your app any permissions it needs. You can also grant your app permissions on behalf of a test user by clicking the ellipsis icon (•••) in the Options column within a given test user's row in the Work Accounts table. Clicking the ellipsis icon will give you the option to edit the permissions the test user has granted your app, generate User access tokens for the test user, and log into the test user's account.

    After you log into the test work account, it is recommended that you assign the business assets needed to go through your app integrations successfully. You can do so by navigating to Business settings to manage your test user’s business manager account and assets assigned to your test user such as pages, ad accounts, and product catalogs.

    Simulate migration with test users

    You can simulate the changes in business permissions that occur when a Facebook user transitions to a work account, allowing you to test the impact of user migrations on your app. To use this feature, visit the Facebook test user, click the ellipsis icon (•••) in the Options column, click Transfer business permissions to work account, and follow the instructions.

    The following prerequisites must be met to use this feature:

  • Create a Facebook test user
  • Ensure the Facebook test user has access to a business account with assets (like pages or catalogs)
  • Ensure the Facebook test user has granted permissions to the business data
  • Create a Work Account test user to transfer business permissions to

    • After you have completed a transfer, you will be able to:

  • Login with the work account to preview the user onboarding experience
  • Fetch user_access_expire_time fields with Facebook test user’s User Access Token

    • User onboarding experience

    Meta is delaying the potential disruption by offering a 30-day grace period, where the User/Page Access Token backed by Facebook user still has access to the business assets via third-party APIs. During the 30-day grace period, the user needs to reauthenticate on a third-party Tech Provider’s surface and create a new access token for the Tech Provider to store. By “reauthenticate”, the user has to authenticate with their MWA identity, reselect the same set of business assets, and pass back business permissions to the Tech Provider in the form of a new access token. If that 30-day grace period passes and the user has not authenticated or is still using their personal FB account, the API call will start failing.

    Meta has a persistent 30-day banner in Business Manager that counts down and shows all the third-party apps that the user needs to re-authenticate with their work accounts. If a third-party app is only using a System User Access Token (SUAT), it will not show up in the section since Meta work account migration doesn't impact system users.

    30 day banner and popup

    Migration APIs and troubleshooting

    The Meta work account migration APIs and troubleshooting documentation provides information on how to determine which users and Business Accounts are migrating, their expiration date, and whether they are a work account or not. is_work_account is a boolean return type that indicates whether the user is using a work account or not. It is available in the User object. The user_access_expire_time field is a timestamp that indicates when the user's access to specific assets will be revoked. After this timestamp has passed, the user is expected to no longer have manage access to the assets. Subsequent API calls using the Facebook user's access token needing to access these specific assets will start returning permission errors. user_access_expire_time is available on the following objects:

    Limitations

    user_access_expire_time has certain limitations. It will only return expiration time data of assets which the user has explicit access through business permissions of the migrating business. For example, the data will only return a timestamp if the Facebook user is an admin of the Page through a migrating Business Account. Pages owned by the migrating business that are not directly assigned to the user will not yield a timestamp.

    Recommended usage

    The data can be used in various scenarios to enhance the functionality of your application and proactively reduce authentication and permission issues your end customers may encounter:
    • Debug whether access tokens received from your customer belongs to a work account
    • Debug when a user's access to business assets will expire
    • Send notifications or reminders to users when their access to specific assets is about to expire, and prompting them to authorize using their work account to retain functionality
    • Handle API errors by detecting expired access and providing appropriate error messages or instructions to users to connect with their work account with access to those business assets

    Example Graph API Calls

    1. Retrieving is_work_account status

    Request
    GET /v17.0/{user-id}?fields=is_work_account
    Response
    {
  "id": "{user-id}",
  "name": "Romane Richter"
  "is_work_account": true
}
    2. Retrieving user_access_expire_time during a 30 day window

    Request
    GET /v17.0/{object-id}?fields=user_access_expire_time&access_token=<access-token>
    Response
    {
   "user_access_expire_time": "2023-06-23T12:00:00+00:00"
}
    3. Request to field before migration will return empty data

    Request
    GET /v17.0/{object-id}?fields=user_access_expire_time&access_token=<access-token>
    Response
    {}
    4. Requests 30 days after migration (after `user_access_expire_time`) will likely throw errors

    Request
    GET /v17.0/{object-id}?fields=user_access_expire_time&access_token=<access-token>
    Response
    {
  "error": {
    "message": "(#100) Object does not exist, cannot be loaded due to missing permission or reviewable feature, or does not support this operation. This endpoint requires the 'pages_read_engagement' permission or the 'Page Public Content Access' feature or the 'Page Public Metadata Access' feature. Refer to https://developers.facebook.com/docs/apps/review/login-permissions#manage-pages, https://developers.facebook.com/docs/apps/review/feature#reference-PAGES_ACCESS and https://developers.facebook.com/docs/apps/review/feature#page-public-metadata-access for details.",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "AZdHiJUBflrZnE-RNKrHAah"
  }
}

    Permissions and Errors

    To access user_access_expire_time and make API calls to it, developers should ensure that the required permissions are granted to load these objects. In the provided examples, if object-id is referring to a business object id, then the user must have been granted at least the business_management permission to load the object. Please refer here for more details.
    When attempting to access an asset after the expiration time, the API response should return a generic error with 100 and the type OAuthException. This indicates the object is no longer accessible via API, since the user no longer has access to the asset.

    See Also

    Visit the Tech Provider Integrations FAQ.