Permissions

Overview

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.

The permission controls when editing a custom integration app

Available 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 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.

PermissionDescription

Read group content

Read posts and comments in selected groups.

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 content

Manage posts and comments in selected groups.

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.

Report group content

Report inappropriate posts and comments.

Allows the app to report posts for admins to review directly via the Graph API by making a POST to the

/community/reported_content

edge.

Apps can report content, but moderation can only be done by a person that has the Community Admin role.

Mention bot

Where mentioned in a post, see the post and reply to comments.

Use this permission for building bots in Workplace Groups.

Manage groups

Create, edit or remove selected groups and their members.

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 accounts

Provision, update or deactivate accounts via the Account Management API.

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.

Read user email

See any group member's email address.

This permission allows you to fetch the email account associated with a Workplace user's account.

Impersonate account

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 posts on behalf of users.

Impersonate tokens can only be retrieved for accounts that were claimed.

Message any member

Send and receive chat messages to and from any member of your community.

Use this permission for building bots in Work Chat.

Read all messages

Read chat messages from any member in your community.

Use this permission to enable a compliance integration that will monitor Workplace Chat usage.

Read security logs

Access details of security events, including login attempts and password reset requests.

Use this permission to enable a compliance integration that will monitor Workplace Chat usage.

Group-Level Permissions

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.

Enabling a custom integration for a specific group.

Group-level permissions apply to the following permissions:

  • Read group content - Read posts, comments and member profiles in selected groups
  • Manage group content - Manage posts and comments in selected groups
  • Manage groups - Edit or remove selected groups and their members

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 allow group admins to enable for their groups.

Admin Install Flow

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.

An example app which can now be enabled by the group admin.

App Tokens & Usage

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.

The token reset flow for a custom integration app

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.

Token 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.

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.

Adding an IP whitelist to restrict token usage to specified servers