More precision, fewer restrictions

Granular permissions now available for Slack apps

Slack API
Slack Platform Blog
4 min readJan 21, 2020


Illustration and design by Casey Labatt-Simon.

We recently introduced the Slack app toolkit — the happy path for building apps that anyone can easily discover, understand, and use in Slack.

Permissions, or the way apps request information in Slack, are the first component of the toolkit. We’ve redesigned the bot token with a revised permissions model called granular permissions. Now you can request only the information needed for your app to function and drive deeper adoption among security-conscious customers.

This year, we will require granular permissions for Slack apps listed in the App Directory. To learn more, read on.

Reducing scopes

As a general security practice, many admins operate under the principle of least privilege, which restricts a user’s access to the minimum permissions needed to perform their work. So, before users can try out your app in their Slack workspace, they must first get approved by security-conscious admins. With a redesigned OAuth page, admins can now see exactly what your app can view and do in their workspace.

Before granular permissions, apps using the bot token received a broad set of scopes; developers did not have a way to pick and choose the information their app actually accessed. Now, with granular permissions, you can specify the exact scopes needed for your app to function.

Imagine a Slack app for reporting and approving expenses. Before granular permissions, this app would have been issued a blanket set of scopes. In that world, below is what an admin would see when reviewing the app. You’ll notice this app requests access to information it probably doesn’t need — like `channels:history`, the ability to fetch the history of messages in a channel. As a result, an admin may be less likely to approve it.

An app that does not use granular permissions displays all scopes on the OAuth page.

Consider the same Slack app using granular permissions. A developer could select only what their app needs and exclude unneeded scopes, like `channels:history`, to get the benefit of a less-permissive app. You’ll notice the page is simpler to review — and less intimidating for the admin.

An app that uses granular permissions likely displays less scopes on the OAuth page.

Building for the enterprise

PLAID, a Tokyo-based analytics company, launched a new Slack app for their customer experience platform, KARTE — a service that delivers real-time data and analytics reports to users.

KARTE shares real-time customer insights in Slack.

The KARTE team’s priority was to drive adoption of their service, particularly among security-conscious customers. Using granular permissions enabled KARTE to request the minimum number of scopes and increase their likelihood of adoption within the enterprise.

KARTE uses granular permissions to list fewer scopes on the OAuth page.

Improving app reliability

Granular permissions also offer more reliability for you and your app’s users. Apps using this model will continue to work, even when the original installer leaves a workspace.

For instance, Donut, a team-building app for Slack, gets installed once by a single person — but hundreds or thousands of people might use it within Slack to connect with their teammates.

Donut introduces two users in Slack, providing context and scheduling help.

Donut was initially built with a user token. Due to the limitations of that token type, when an app installer left their company, the Donut app automatically uninstalled. Now with granular permissions, the app will remain on a workspace without interruption.

Adding incremental scopes

Granular permissions give you more flexibility to add incremental functionality to your app — without the hassle of managing several tokens. That’s because we’ve wrapped all app functionality into one, streamlined bot token.

Simple Poll, a polling app for Slack, previously elected to build on the user token. While the token was less permissive, it also meant that Simple Poll missed out on some of the functionality offered by the bot token. By migrating to granular permissions, Simple Poll can make updates to their app or request new scopes as needed.

By upgrading to granular permissions, Simple Poll is able to build new functionality, like recurring polls.

“An added benefit is that we’re aligning Simple Poll to the favored permissions model that will unlock future capabilities,” said Simple Poll founder, Wilhelm Klopp. “We want to be on the model that Slack is recommending and investing in.”

Getting started

We recommend all apps build on this foundation to take advantage of future Platform features. Get started by reading permissions documentation.

Starting February 21, 2020, the App Directory will require newly submitted apps to use granular permissions. Existing Slack apps on the App Directory must update by the end of 2020. Refer to the migration guide to learn how to upgrade your app.

Thanks to your feedback, we are making ongoing improvements to granular permissions in the coming weeks. Continue to share with us by emailing

Looking for hands-on support? Save your spot for the Slack app virtual hackathon today.



Slack API
Slack Platform Blog

Tips to integrate with Slack APIs to make your work life simpler, more pleasant and more productive — whether for your internal team or millions of Slack users.