In September 2025, we will discontinue support for classic apps. For your apps to continue working, you will need to migrate them to Slack apps. Any custom bots or classic apps you have built will no longer work after these dates. Refer to this changelog article for more details.
If you're a developer who has built an app on the Slack platform in the past, you may know that apps have since changed. With the help of explicit permissions tied to the app rather than an installing user, Slack apps are more pleasant to build and install.
Slack apps act independently of an installing user. They have more functionality, and they're more likely to be approved by a Slack admin—and less likely to be accidentally uninstalled.
Good news: existing, classic apps won't be left out in the cold. You can migrate an existing app to use the new system of permissions. Along the way, you'll gain more control over the permissions you request.
Before starting migration, you can read our guide to building a Slack app from scratch if you've never built a Slack app before. Otherwise, read on to start your app's great migration.
Migrating your app is a trip in two parts.
First, you'll update your app's scopes on its Development Workspace, the workspace where you originally built and tested your app. To change the scopes your app has on the workspace, you'll follow the update UI and touch no code. At the end of the update flow, you'll obtain a new OAuth redirect URL.
Secondly, you'll change the URL where you redirect users to initiate the v2 OAuth flow. The v2 OAuth flow is nearly identical to the old OAuth flow. The only differences are a couple new v2s added to method names and a slightly altered structure for the final oauth.v2.access
response.
Start your journey with a tiny first step—read on.
This section of the migration guide walks you through updating scopes for your app on its Development Workspace. All of the migration here is powered by a UI; you won't have to touch a line of code.
Updating your app begins close to home: your App Management page. When you navigate to your app's page, your classic app will now display a Tools section in the sidebar. Select Update to Granular Scopes to begin your app migration.
Work through the checklist on the Update your app's scopes page to select the right scopes for your newly scope-conscious app.
The scope updater page does not automatically select the specific scopes your app needs. You'll still need to individually select the right scopes for your app.
Read through each part of the checklist and select the scopes needed. If you're not sure whether you need a particular scope to call a Slack API method or to listen to a Slack API event, look at the reference pages for methods and events to see details on what scopes are needed for each.
You'll notice that incoming webhooks and Slash commands are attached to your app's bot user only, rather than an authenticated user. That's great news: it means that webhooks and Slash commands no longer unexpectedly get uninstalled when an installing user departs. If you use either webhooks or Slash commands, add the incoming-webhook
or commands
scopes.
If your app used the deprecated umbrella bot
scope, you'll see that all the scopes contained in it— all the permissions that the bot
scope previously conferred on your app—are already checked in the checklist.
You probably don't need each of those scopes (for example, the remote_files:*
scopes are rarely required), which is why the old umbrella bot
scope caused some problems in the first place. Uncheck the scopes you don't want!
You'll find fancy new features that previously required a user scope, now available to your app's bot user. Request these scopes for your bot and not the equivalent user token scopes.
Rule of thumb: Slack apps nearly all work from the perspective of the app, not from the perspective of an installing user. If you're not sure whether to select a bot scope or user scope, select it as a bot scope.
One last aside: if you're worried about taking a wrong step, remember that this update tool only applies to your app on its Development Workspace. Missteps are no big deal. If you miss a scope that your app eventually requires, your app will receive an error from the Slack API noting which scope it needs. Once you add that scope, request it via the App Management page, and you'll be on your way.
After selecting all the bot user scopes your app needs, click Continue to select user scopes—i.e., scopes that allow you to act from the perspective of the installing user.
These scopes should be restricted or avoided if possible. Only request a scope for acting as your authenticating user if the action needs to be performed from the user's perspective: for example, reading or starting group DMs for a specific user.
Slack apps may not access the legacy RTM API. For most apps, the Events API lets your app listen to Slack goings-on in a more structured, safe way. If you require access to the legacy RTM API (say, because you're building your app behind a corporate firewall), continue to use a classic app bot token to call rtm.connect
.
After one more Continue, you'll see a Verification page that shows you all the scopes your app now requests during installation.
If the list seems long, rest assured that admins and installing users will now have a much clearer idea of what your app can actually do. And your app is less likely to be accidentally uninstalled if an installing user departs. Select Yes, this looks good.
You'll see a button on the following page that allows you to reinstall your app with the granular scopes. Before you click the button, copy down the OAuth redirect URL listed at the bottom of the page. You'll use that in part 2 of migration, where you slightly change your OAuth flow to receive granular scopes on other workspaces.
Click Reinstall. Congratulations, your app now uses new permissions on its Development Workspace and can act independently of the installing user!
If your app is not distributed beyond your development workspace, your migration is complete. Touch down in the sand, stretch your feet out, grab some coffee, and go on with life in the new land of apps. Check out the quickstart guide to see a list of differences between classic apps and granular Slack apps.
If your app is distributed to other workspaces, you'll want to update your OAuth flow. Read our guide to the Slack V2 OAuth flow. You don't have much additional migration ahead of you! With the redirect URL obtained above, you'll automatically initiate the new V2 OAuth flow whenever you redirect a user. Then, you'll have to update to the oauth.v2.access
method, which you call after obtaining a temporary code from the installing user. After parsing the slightly different endpoint response, you'll be ready for reinstall.
Now that you've updated your code to the Slack V2 OAuth flow, you'll want to make sure your app is reinstalled on each workspace. You might gently direct users to reinstall with a DM containing an updated redirect to your oauth/v2/authorize URL. If you're comfortable forcing a reinstall, you can even use the auth.revoke method to revoke a previous installation on a given workspace.
Remember, there's no hurry to force a reinstall if you're comfortable dealing with two sets of scopes at once, depending on whether each installation of your app is a classic installation or uses the new V2 flow. However, for simplicity we think it's easiest to get all installations of your app updated to new permissions as soon as possible.
There's no automatic way to convert existing bot and user tokens into the new kind of app, except on your Development Workspace using the update UI.
If your app is listed in the Slack Marketplace, migrating your app requires a little more care. Upgrading your app to granular permission will likely mean creating a separate testing app that we can install and test.
As an example, if your app is called cycling_tips
, create a staging app called cycling_tips-dev
that we can install. You can use this staging app to test updates.
Creating a distributed, staging version of your app allows us to test how the new scopes will work on your app, leaving your published (live) app as is until those changes can be approved. The staging app should use the same scopes requested in the resubmission for your published app.
You can add these details to the test instructions box in the "Help us review your app" section when you resubmit. If your web service requires an account or a paid plan to access, please include test details for this as well.
If it's been a while since you’ve submitted your app, or if you're also making other changes to your app, please review our general guidelines again.
Check out our quickstart guide for a rundown on updated behavior for Slack apps.
User scopes and tokens should only be requested as necessary when the app must perform an action on behalf of the user.
Slack apps can explicitly request the ability to post in any public channel using the chat:write.public
scope.
as_user
parameter for chat.postMessage
? Slack apps typically act and post on their own behalf. However, if you'd like to adjust the authorship of your app's messages, request the chat:write.customize
scope. Read the chat.postMessage
documentation for more details.
If you are using the legacy RTM API for security reasons with an app you’ve built for your own team (internal integration), check out Socket Mode.
If your app is distributed, you’ll first need to identify the events your app is consuming from Slack’s RTM API and determine their equivalents in the Events API. Once you’ve done that work, you’ll need to configure event subscriptions in your app configuration, as well as an endpoint where Slack can send those event payloads. Store the data your app is consuming from the Events API as you currently do with RTM events.
Besides the legacy RTM API being a much more robust and undiscerning stream of events from Slack, there are a few features not available in the Events API.
rtm.start
is not available via the Events API.Read on: Events supported by the legacy RTM API and the Events API.
At this time, there's no way for Slack to determine which scopes your app needs. You'll have to run through each method and event that your app makes use of, requesting the scope for each.
The legacy bot
scope consisted of many scopes that are now broken down and requested separately, allowing developers to request the least access possible on a Slack customer workspace. The new scopes are a better, more honest representation of the permissions your app has on a workspace. Ensure that you request only the scopes absolutely necessary to enable your app’s features in Slack. When your app goes to our Slack Marketplace team for review, they will review your app’s use of each scope.
Discontinuing new classic Slack app creation
You won't be able to create new classic apps or legacy custom integration bot users anymore after June 4, 2024. Learn how this may impact you and your team.
If you still need to create a classic app, either to use the rtm.connect
method, or for any other reason you may continue to do so until June 4, 2024.
In order to migrate users, direct them to reinstall via a DM containing an updated redirect to your oauth/v2/authorize
URL.
Classic bot tokens will continue to work after another user has installed the app using V2 OAuth.
No, once an app’s configuration has been migrated it’s no longer possible to use the V1 OAuth endpoint.
To assist with migrating to granular permissions, we recommend that developers create a separate Slack app for testing and use in their development/staging environments, e.g. [app_name]-staging. This provides a few of key benefits:
Use this app to test your granular permissions before adding these new scopes to your published app’s settings and resubmitting. Please be sure to include instructions for how to install the app you tested with in your submission.
Unfortunately there is no avoiding a small window of time where app installations cannot be performed while the switchover is taking place. The best way to coordinate this is to first deploy any code changes required to update the authorization flow, and then publish your app’s changes as the latter process will take effect almost instantaneously.
Submissions should be made as soon as possible, and can be made by visiting the Slack Marketplace, navigating to the app in question, and heading to the Submit changes for review section.
Yes, we can roll the app back to the previous set of non-granular scopes your app is using if you confirm the scope list with us. The most common reason for rollback is an app developer migrating an app’s OAuth settings and scope selections before any development work has been done.
Note: it is a complicated process and there may be a delay in the rollback.
As of December 2020, we no longer accept new classic app submissions or updates to classic apps.
As of May 27th, 2022, granular permissions have been required for apps in the Slack Marketplace.
As part of reviewing your resubmission we need to be able to install and test a version of your Slack app that is using the new granular permissions, e.g. the Slack app you use in your development/staging environment.
We cannot use your published app to test with, as it is restricted to requesting approved scopes.