Apps & Permissions

Overview

Custom integrations on Workplace are services that use the Graph API or the Account Management API to extend the default functionality of Workplace. For example, custom integrations can keep employee information up to date, automate group membership, make backups of posts in groups, or automate posting to specific groups based on activity in another service.

Apps on the Integrations tab in Company Dashboard.

As a Workplace system administrator, you can control the capabilities offered to each custom integration by creating apps and granting them specific permissions. Each app can be named to reflect the service it enables. Apps come with unique access tokens and permissions to control what information is allowed to be read or written by that app.

This guide describes the app and permission model in more detail, and covers the following topics:

Creating Apps for Workplace

The Graph API and Account Management API for Workplace are openly available APIs, which can be called by any developer that knows how to call REST-based APIs. However, access to these APIs is controlled by app permissions and protected by access tokens, and only System Administrators can create apps and generate access tokens.

To create an app for Workplace, follow the steps below:

  1. In the Company Dashboard, open the Integrations tab.
  2. Click on the Create App button.
  3. Choose a relevant name and description for the app.
  4. (Optional) Add a profile picture for the app. This will be used any time the app makes a post, which requires the Post to groups permission.
  5. Choose the required permissions for the app, based on the integration functionality you require.
  6. Copy and safely store the access token that's shown to you. You'll need this when making API calls.

As a system administrator, it's important to make sure that you only share access tokens with trusted developers within your organization and Facebook-approved third-party developers.

App Permissions

Each Workplace app can be granted its own set of permissions to control the level of functionality available to it on the Graph API and Account Management API.

When you create an app and grant it permissions, those permissions are applied to every account in your community. Account holders don't need to grant additional permissions to the app in order to benefit from its functionality. This differs from the permission model on consumer Facebook, where each user individually grants permissions to an app when logging in.

Below is a full list of the app permissions available to custom integrations, along with an overview of how they can be used.

Read content
  • Read posts and comments in groups, retrieve files and read information from member profiles.
  • Use this permission when building any custom integration that fetches content, such as an e-discovery tool or an offline content moderation tool.
Post to groups
  • Post and comment in any group
  • Use this permission when building a custom integration that posts content to groups, such as a weekly report from an internal service, or a service status notification bot.
Manage groups
  • Add, edit or remove groups and their members
  • Use this permission when building a custom integration that auto-generates groups and populates group members based on org chart structure or project groups.
Manage accountsImpersonate
  • Post and comment in groups and read messages on behalf of any user
  • Use this permission for generating member access tokens to fetch Work Chat conversations for a specific user, and for making or editing posts on behalf of users.

App Tokens & Usage

When you create a new app for Workplace, an access token is generated for use with the Graph API and Account Management API. This access token will only be shown once, so it's important to store the token securely for later usage in code.

Workplace app tokens never expire, and do not need to be refreshed unless they have been manually reset. If you edit the permissions available to a given app, the existing token will still work, and you won't need to generate a new token.

If you ever need to invalidate a token, you can reset the token via the Reset Token button in the Edit app dialog. A new token will be generated and displayed, and the existing token will be immediately invalidated.

App Security

Access tokens are powerful. They grant access to your company's data on Workplace. When creating an app, consider the minimal set of permissions necessary to complete the integration features, and don't grant any unnecessary permissions.

When storing tokens or adding them to code repositories, great care should be taken to ensure that they aren't shared with the wrong people.

Never commit production access tokens into public code repositories. Never deliver access tokens in client-side code, such as JavaScript or mobile apps.