To deploy your app across an entire Enterprise organization, you'll need to make your app easily installable by an Org Admin.
When an Org Admin installs your app across the entire org, it is not added to any workspaces in the org. However, from that point on, the Admin can add your app to many workspaces at once, dramatically simplifying app installation for large orgs.
To install your app on an entire org, read on, starting with a quick refresher on how app installation works for all Slack apps.
As a reminder: a Slack app can be installed either via the UI in the app config or via the OAuth flow.
The same is true for org-wide apps; an app installed via the app config will generate the org-wide token automatically whereas an app installed via OAuth will require the handshake to succeed to programmatically generate the token.
Generally, if you are building an app for your own organization with no plans to allow other organizations to install it, using the app config is the most straightforward way to install the app. You will also need to enable private distribution for your app so that it can be granted access to the workspaces in an org. To enable private distribution, find the Manage Distribution section in the app config sidebar and choose Private Distribution.
If you plan on making your app available for others to install, or list it in the Slack app directory, you should use OAuth. Both installation methods provide the token your app will use to interact with the Slack platform APIs.
The good news: the OAuth process is nearly identical for an app. It's actually the installing Admin who decides to install your app on the organization as a whole.
The rest of this guide walks you through the additional things you'll need to keep in mind when using OAuth to install your app on an entire Enterprise organization. Regardless of how the app is installed, the org-wide token behaves the same and requires the same changes to how your app is developed.
First things first: you'll want to specify in your app config that your app may be deployed to an entire Enterprise org.
Find the Org Level Apps section in the app config sidebar, and press the Opt-in button.
You will need a Bot Scope like team:read in order for the Opt-in button to be enabled. This scope won't actually be used.
That's it: your app can now be installed by an Org Admin or Owner at the organization level, rather than on an individual workspace.
Installing your org-wide app via OAuth is nearly identical to a single-workspace app's installation. You can get a refresher on the Slack OAuth process here.
The only additional consideration for OAuth with an org-wide app is that you need to determine whether the installation happened on an organization, as opposed to a single workspace.
In order to do that, look for the is_enterprise_install field in the response from oauth.v2.access:
{
"ok": true,
"access_token": "xoxb-XXXX",
"token_type": "bot",
"scope": "identify,users:read",
"bot_user_id": "W0XXXX",
"app_id": "A0UXXXX",
"team": null,
"enterprise": {
"id": "E1XXX",
"name": "Starship"
},
"is_enterprise_install": true,
"authed_user": {
"id": "WXXXX",
"access_token": "xoxp-XXXX"
...
}
}
Keep in mind: even once an Org Admin installs your app across the entire Org, it has not yet been added to any workspaces in the org yet.
Because of that, once OAuth has completed, you'll likely want to redirect an installing Admin back to a modal that will add the app to individual workspaces. For example:
https://app.slack.com/manage/{your-org-id}/integrations/profile/{your_app_id}/workspaces/add