Slack apps start life residing in one workspace. Distribution allows apps to spread their wings and take off for new pastures.
The type of distribution you choose for your app will determine which installation flows you'll need to build.
In this overview, we'll run through the different types of distribution, and explain how to install and authenticate users for each.
When you create your Slack app, you associate it with a workspace. Your app can be installed to its associated workspace easily with a couple of clicks.
Just open the app dashboard for your app, select the Install App section, and click the Install App to Workspace button.
After installing your app, you'll get a single access token that can be used to authenticate API calls on behalf of the app.
Single-workspace apps can use the full range of app capabilities, but can't be distributed to any other workspaces.
If your single-workspace app needs to take action on behalf of other users, you'll need to build an OAuth 2.0 flow.
A lot of apps will be completely content staying at home like this—public distribution is a completely optional step that isn't right for every app. Read on to learn why you might want to distribute your app.
By default, newly built Slack apps can only be installed in their associated workspace. Installing your app on other workspaces means learning the songs and waltzes of OAuth 2.0.
Once you've built an authorization flow using OAuth 2.0, your app will be able to generate access tokens for each workspace—and user—on the fly. This is one of the key steps to letting your app roam free.
Before your app can soar from workspace to workspace, there's some preparation required.
When first created, your app can be installed to its associated workspace without any code for handling authorization.
The one-click install of a single-workspace app generates an access token. That access token can then be used to authenticate all sorts of API requests, but only within that associated workspace.
When you're planning to share your app with other workspaces - whether one or one thousand - you need to handle authorization. This will allow your app to be installed to any arbitrary workspace, generating and using an access token programmatically.
This process works using the familiar protocol of OAuth 2.0. Read our guide to using OAuth to understand the flow required for your app to request permissions and generate access tokens on the fly.
Once in the wild, your app could be installed to a Slack organization that uses Enterprise Grid. So it makes sense to understand how Grid can affect the way your app works, to prevent buggy behavior.
Read our guide to supporting Enterprise Grid in apps to prepare properly.
Onboarding users is an important consideration for any app. For those apps that are publicly distributed, it is especially crucial—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.
Creating a helpful and engaging onboarding flow will help your potential users become experts without any hands-on support.
Slack apps open to installation by other workspaces have additional security requirements. Your app must support SSL for all:
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 features where users can't directly install apps but can solicit for installation through a guided interface. Administrators may then screen these requests and selectively approve for installation.
We don't have any technical guidelines for handling this, your app either will or won't be approved. However, ensuring that your app design follow our guidelines might improve your chances of admin approval.
The list of permissions that an app requests will also be important to the decision an admin makes—ensure that your app only requests permissions it absolutely needs.
If you think you're ready to takeoff, launch your app into the world of public distribution:
Once public 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, and an HTML meta tag to enable Slack app suggestions.
That's it! Your app is now soaring through the skies of the Slack app ecosystem. We hope your journey is a great success.
You can also go a step further and submit your app to the Slack Marketplace.
After distribution has been activated, you have the option of deactivating by clicking on the Deactivate Public Distribution button in the same location you enabled it.
This will remove the app from any workspaces that have installed it, aside from the originally associated workspace.
You can not deactivate distribution in this way after your app is published in the Slack Marketplace. Follow the instructions in the Slack Marketplace guide to discontinue your listing.
Your app can be purposefully 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.
Apps will be automatically uninstalled from workspaces under a limited set of circumstances:
bot, incoming-webhook, commands, and identify will generally not be automatically uninstalled.The Slack Marketplace lists publicly distributed Slack apps that have been reviewed to ensure they meet high standards of quality and usefulness.
When your app is capable of being distributed to multiple workspaces, there are a few other adjustments you'll need to make to the app before submitting it for Slack Marketplace consideration.
To learn more, read our Slack Marketplace guide which explains how to increase the chances of your app's approval. That guide also outlines the entire review and submission process.
If your app is approved for listing in the Slack Marketplace, it will gain a listing page. Use this space to tell your app's story, compellingly preview your app's capabilities and user experience, and ultimately attract users. We have some guidelines to help you build a great Slack Marketplace page.
Finally, you can take advantage of direct installs, which allow any user to install your app straight from the Slack Marketplace in a couple of clicks.