When you create a Slack app, it resides in one workspace. You can also distribute Slack apps in either listed or unlisted fashion. In this guide, we'll take a look at the different types of distribution available and explain how to set up installation flows and authenticate users for each.
When you create a Slack app, you associate it with a workspace: to do this, open the app dashboard for your app and click Install App to Workspace within the Install App section.
After installing your app, you'll get a single access token that can be used to authenticate API method calls on behalf of the app.
Undistributed apps exist on a single workspace and can use the full range of app capabilities, but they can't be distributed to other workspaces. In addition, if your single-workspace app needs to take action on behalf of other users, you'll need to build an OAuth 2.0 flow.
By default, a newly built Slack app can only be installed in its associated workspace as mentioned above. Installing your app on other workspaces means that you'll need to set up an OAuth 2.0 flow. Once you've done that, your app will be able to generate access tokens for each workspace and user.
Distributing your unlisted app is perfect for when you want to test out your app by running a pilot for early customers; however, apps intended for commercial distribution should be submitted and approved for listing in the Slack Marketplace. Unlike unlisted distributed apps, apps listed in the Slack Marketplace are reviewed against our requirements & guidelines to ensure a quality experience for end users.
Before you can distribute your app, there are a few steps to complete that are discussed in the following sections.
Once created, your app can be installed to its associated workspace without any code for handling authorization. The one-click install for an unlisted single-workspace app generates an access token, which can then be used to authenticate API requests, but only within that associated workspace.
Therefore, when you're planning to distribute your app to other workspaces, you need to handle authorization. This will allow your app to be installed to any workspace, generating and using an access token programmatically.
β¨ Read our OAuth 2.0 guide to understand the flow required for your app to request permissions and to generate access tokens.
In addition, once distributed, your app could potentially be installed to a Slack organization on Enterprise Grid.
β¨ Read our guide to supporting Enterprise Grid in apps to understand how an Enterprise Grid environment can affect the way your app works.
Onboarding users is an important consideration for any app. For distributed apps, it is especially crucial as your user base could grow from a single workspace to potentially hundreds. Providing direct, hands-on support may be possible with a single workspace, but won't scale once your app is shared with multiple workspaces.
β¨ Read our guide to creating a helpful onboarding flow.
Slack apps open to installation by other workspaces have additional security requirements. Your app must support SSL for all of the following URLs:
Some workspaces will restrict app installation so that only workspace administrators can provide authorization. Other workspaces may only allow the installation of apps officially listed in the Slack Marketplace.
Workspaces can also enable admin approval requirements so that users can't directly install apps, but can request installation via a guided interface. Administrators can then screen these requests and selectively approve apps for installation. The list of permissions an app requests is also important to the decisions admins make, so ensure that your app only requests the permissions it absolutely needs.
If you think your app is ready to be distributed, follow these steps:
Once distribution is enabled, you'll get access to an embeddable Add to Slack button, a shareable URL that kicks off the installation process when clicked, as well as an HTML meta tag to enable Slack app suggestions.
You can also go a step further and submit your app to the Slack Marketplace. This is recommended for apps intended for commercial distribution.
If distribution is enabled, you can turn it off by clicking Deactivate Public Distribution in the same location you enabled it. This will remove the app from any workspaces that have installed it, aside from the original associated workspace.
Note that you cannot disable distribution in this way once your app is published within the Slack Marketplace; instead, you must discontinue your listing there. Follow the instructions in the Slack Marketplace guide to discontinue listing your app.
Your app can be uninstalled at any time from a workspace. Subscribe to the app_uninstalled event if you want your app to receive a notification when this happens.
In addition, apps will be automatically uninstalled from workspaces under the following circumstances:
bot, incoming-webhook, commands, and identifyβwill generally not be automatically uninstalled. However, there is one exception: in the app's associated workspace, the app will be uninstalled when the last creator or collaborator leaves the workspace or becomes a guest user.The Slack Marketplace contains distributed Slack apps that have been reviewed to ensure they meet our standards of quality. Distributing to the Slack Marketplace is the best path for safe and trustworthy third-party apps, and is perfect for when your app has been previously tested with early customers and is ready to be distributed more broadly or at commercial scale.
You can also take advantage of direct installs, which allow any user to install your app straight from the Slack Marketplace.
If your app is approved for listing in the Slack Marketplace, it will have its very own listing page. Use this space to tell your app's story, to give a preview of your app's capabilities and user experience, and to attract users.
β¨ Read our Slack Marketplace guide to help you build a great Slack Marketplace listing page, as well as to learn about the review and submission process.