Workplace from Meta is going away. You will be able to continue using Workplace until 31 August 2025. Visit our Help Center to find out more.
As a Workplace system administrator, you can control the capabilities offered to each 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.
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 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 Facebook, where each user individually grants permissions to an app when logging in.
Below is a full list of the app permissions available to integrations, along with an overview of how they can be used.
Permission | Description |
---|---|
Read group contentRead posts and comments in selected groups. read_group | Use this permission when building an integration that fetches all content from selected groups. If your integration will act as a bot in a group, use the Mention bot permission instead. |
Manage group contentManage posts and comments in selected groups. write_group | Use this permission when building an integration that posts content to groups, such as a weekly report from an internal service, or a service status notification bot. |
Read user timelineSee posts made by group members on their timeline read_user_feed | Use this permission when building an integration that:
|
Manage user timelinePost and comment on any group member's timeline write_user_feed | Use this permission to enable an integration to create or edit a post on a group member's timeline. |
Mention botWhere mentioned in a post, see the post and reply to comments. bot_mention | Use this permission for building bots in Workplace Groups. |
Manage groupsCreate, edit or remove selected groups and their members. manage_group | Use this permission when building an integration that auto-generates groups and populates group members based on org chart structure or project groups. If an integration with this permission is scoped to specific groups, it won't be allowed to create new groups. |
Manage accountsProvision, update or deactivate accounts via the Account Management API. manage_accounts | Use this permission for any integration with an account provisioning service, such as identity providers, the Active Directory Sync Tool or a custom Account Management API client. When you enable this permission, you'll have the option to enable the "Automatically invite people to Workplace as soon as they're added using this integration" permission. |
Manage badgesAward badges to people in a Workplace community. manage_badges | Use this permission to enable an integration to:
|
Read user emailSee any group member's email address. read_user_email | This permission allows you to fetch the email account associated with a Workplace user's account. |
Read work profileRead-only access to people's directory information. read_user_work_profile | Allows an app to fetch people's department, division, organization, primary_address, primary_phone, title, and gender. |
Read org chartRead-only access to people's managers and subordinates. read_user_org_chart | Allows an app to fetch people's manager(s) and subordinate(s). |
Message any memberSend and receive chat messages to and from any member of your community. message | Use this permission for building bots in Work Chat. |
Read all messagesRead chat messages from any member in your community. read_all_messages | Use this permission to enable a compliance integration that will monitor Workplace Chat usage. |
Delete chat messagesdelete_messages | Use this permission to enable an app to delete chat messages from a person's conversations, e.g., to implement a retention policy. |
Read security logsAccess details of security events, including login attempts and password reset requests. receive_security_logs | Use this permission to enable a compliance integration that will monitor Workplace Chat usage. |
LogoutLog members out from all active sessions logout | Use this permission to log a user out of Workplace |
Create link previewsRich previews for links shared in Workplace. link_unfurling | Apps with this permission can generate authenticated previews for links that are shared in Workplace. |
Manage Work ProfilesRead and update work profiles in Workplace. manage_profiles | Apps with this permission combine the reading permissions of read_user_work_profile and read_user_org_chart. Apps with this permission also are able to update account information (e.g.: Name, department, division, title, organisation, phones) |
Provision User AccountsProvision accounts in Workplace. provision_accounts | Apps with this permission can provision, deactivate and delete (unclaimed) Workplace accounts. This permission also allows updates to the active, email, name, hire_date, and invited member's fields. |
Read group membershipList the members of a group and list the groups that a user is a member of list_group_members | Apps with this permission can query the list of members of a particular group. Furthermore, it is possible to list the groups that a user is a member of. |
Manage Knowledge Library contentCreate, edit and delete important company information in Knowledge Library manage_knowledge_library | Apps with this permission can create and modify content within Knowledge Library. Use this permission to enable an integration to:
|
Read Knowledge Library contentRead important company information in Knowledge Library read_knowledge_library | Apps with this permission can access content from Knowledge Library. Use this permission to enable an integration to:
|
Export employee dataExport the list of current employees and their activity data in a CSV format. export_employee_data | Apps with this permission can schedule a data export job which generates a CSV file listing all Workplace users. The CSV also includes data on the user, as well as information on their recent use of Workplace features. |
Group Chat BotEnabling bots to interact in group chat. bot_group_chat | Apps with this permission will enable them to interact with members in a Group Chat. Use this permission to enable an integration to create or manage a multi-person group chat. This permission is dependent on |
Manage SurveysCreate, update, delete and read survey configuration manage_surveys | Apps with this permission can create, update, delete and read survey configuration. |
Read surveysRead surveys configuration and receive webhook updates related to surveys read_surveys | Apps with this permission can read surveys configuration and receive webhook updates related to surveys. |
Read surveysRead surveys configuration and receive webhook updates related to surveys read_surveys | Apps with this permission can read surveys configuration and receive webhook updates related to surveys. |
Read People SetsRead People Sets read_people_sets | Apps with this permission can See Dynamic People Set configuration and subscribe to updates related to people sets |
Manage people setsManage people sets manage_people_sets | Apps with this permission can create, update and delete people sets in the Workplace community |
Read important postsRead important posts read_important_posts | Allows the integration to read information about the important post promotions – both currently active and expired. |
Manage important postsManage important posts manage_important_posts | Allows the integration to mark group posts as important, making them appear on top of the feed, and allows to stop the important post promotion prematurely. |
Remove profile informationRemove personal information for a deactivated user. remove_profile_information | Allows the integration to remove profile fields such as name and profile image from deactivated users on Workplace. |
For some permissions, it's possible to limit an integration to be enabled on specific groups. This allows you to scope an integration's access to just the content you want to expose.
For example, you can allow an alert-posting integration to post only in a team's own group, or enable an employee app integration to read content only in specific open groups.
To specify group-level permissions for a custom integration, use the Group Access panel in the Edit Integration dialog.
Group-level permissions apply to the following permissions:
You can configure an integration such that group-level permissions can be applied to either All groups, Specific groups as chosen by a system administrator, or Let group admins enable for their groups.
When Let group admins enable for their groups is enabled, an admin of a group will see a new Integrations tab under the Manage Group screen, allowing them to enable the integration on their group.
When you create a new app for Workplace, an access token is generated for use with the Graph API, Account Management API, or Webhooks.
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 Access Token button in the Edit App dialog. A new token will be generated and displayed, and the existing token will be immediately invalidated.
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.
You must store and use your API Credentials only in your own server environment and ensure that these values are never copied or transmitted elsewhere, e.g., to mobile apps or web browser clients.
To add an additional layer of security for integrations, you should add an IP whitelist, which will restrict token usage to servers only on the whitelisted list of IP addresses.
If a custom integration makes no calls using a particular permission for 30 days, that permission will be removed. After this has happened once for a custom integration, an option will be available to stop this removal process.
If a valid webhook subscription has been set up, the webhooks sent by this count as a use of the relevant permission.
Access tokens for Workplace don't expire. Custom integrations can require an app secret proof to add an additional layer of security. Enabling the 'Require App Secret Proof' option ensure that API calls are only ever made from server-side code, an expiring app-secret proof will be required along with a the access token when making API calls.
To generate an expiring app-secret proof, you'll need to concatenate the token with a unix timestamp, separated by a pipe symbol |
, then create a SHA-256 hash of the concatenated string, using your app secret as the key. Here's an example in PHP:
$appsecret_proof = hash_hmac('sha256', $access_token.'|'.time(), $app_secret);
Some Operating Systems and programming languages will return a timestamp that is a float. Be sure to convert to an integer value before calculating the app-secret proof. Some programming languages create the hash as a digest object. Be sure to express the hash as a hexadecimal object.
To make API calls with your app-secret proof, pass the generated hash via the appsecret_proof
parameter, along with the appsecret_time
set to the timestamp you used when hashing the app secret, along with your access token.
GET https://graph.facebook.com/v2.9/community/groups? &access_token={access-token} &appsecret_proof={appsecret_proof} &appsecret_time={appsecret_time}
Time-stamped app secret proofs will be considered expired after 5 minutes, so it's recommended that you generate a new proof in-line when making each Graph API call.
Postman is a widely used tool for working with web APIs. You may find it convenient to explore the Workplace API using Postman, but the $appsecret_proof
parameter presents a complication - since this value must be calculated and expires after five minutes, it would simplify matters if Postman could generate the value at request time. In fact Postman can do so using its Prerequests Scripts & Params features. This script can be used as a starting point:
// Add to Postman's Pre-request Script Tab var access_token = "replace-me"; var app_secret = "replace-me"; var time = (new Date().getTime()/1000|0); postman.setEnvironmentVariable("access_token", access_token) postman.setEnvironmentVariable("appsecret_time", time); postman.setEnvironmentVariable("appsecret_proof", CryptoJS.HmacSHA256(access_token + '|' + time, app_secret));