Permission Scopes

Permission scopes grant access for your app to perform functionalities in Slack. They define the API methods your app is allowed to call. Although Slack provides a comprehensive list of permission scopes, your app most likely only needs a handful of them.

When creating your Slack app at api.slack.com/apps/, you can add or remove scopes in one of several ways.

• In the app manifest on the App Manifest page
• On the OAuth & Permissions page

See Sample Apex SDK for Slack App for an example manifest.

To determine which scopes your app needs, understand which events or methods your app requires first.

For example, if your app checks if a private or public channel exists, it requires the conversations.list method so you can get the names of private and public channels. You can then determine that your app needs the channels:read and groups:read scopes.

Then, if your app also creates a channel, it requires the conversations.create method, which works with the channels:manage scope.

Next, work with the Slack Web API methods using the Apex classes. In this case, conversations.list corresponds to the ConversationsListRequest and ConversationsListResponse Apex classes.

Here's a list of basic scopes common to Slack apps created with Apex SDK for Slack.

For the complete list of scopes, see Permission scopes.

Some scopes are unique to a particular token type, for example, bot or user token.

• Bot tokens are ideal for most apps. They provide granular permissions to request only the scopes your app needs.

• User tokens allow you to work directly on behalf of users.

The permission scope to perform a task can often apply to both the bot or user. When picking either a bot or user token for your app to perform tasks, consider your user's experience. It depends on what your bot is allowed to do based on its permissions and what your users are allowed to do in a workspace.

For example, bots are only allowed to post in channels where they are members. Bots can't post to a DM conversation between two users using chat.postMessage, which is handled by the Apex ChatPostMessageRequest and ChatPostMessageResponse classes.

Bot token strings begin with xoxb-. Bot tokens are not tied to a user's identity and will remain installed when an installing user is deactivated.

One of the most common scopes your app can use with a bot token is chat:write, which enables your app to post messages in approved channels and conversations.

Alternatively, set the chat:write and chat:write.customize scopes on the bot token while setting the username and icon_url properties. The chat:write.customize scope sends messages as @your_slack_app with a customized username and avatar.

Bot users and bot tokens can be used with a restricted set of Slack Web API methods. For example, bots.info is handled by the Apex BotsInfoRequest and BotsInfoResponse classes. See API methods available to bots.

User token strings begin with xoxp-. Use user tokens with care as they take actions on behalf of users.

One of the most common scopes your app can use with a user token is chat:write, which enables your app to post messages on the user's behalf.

Updating scopes in Slack or a Slack app can cause installation issues if the scopes become out of sync with the Slack app's core definition.

We recommend updating your scopes as follows.

1. Update scopes in your <appname>.slackapp-meta.xml file. See SlackApp.

2. Deploy your scope update to your org.

3. Update the scopes from http://api.slack.com/ for your app in the Slack app manifest. To find the Slack App manifest:

   • View your Slack apps at api.slack.com/apps.
   • Select the app you want to view from the list.
   • In the sidebar, select Features > App Manifest.

4. To update the Slack app in the Slack app directory, get the app re-approved.

• Access Tokens
• Understanding OAuth scopes for Bots