If you want your Slack app to reach the most people, build an app that can be deployed across an Enterprise Grid organization with multiple workspaces.
Here are some of the benefits for your users:
Organization-wide apps are installed once at the organization level and have a single token that represents the permissions for the app on multiple workspaces.
An organization-wide app isn't automatically added to every workspace in an organization. The app is authorized once for an entire organization using OAuth. Admins can then add it to workspaces in the organization without further authorization.
Although apps that are installed on an Enterprise organization look similar to apps installed on a single workspace, there are a few changes to be aware of before you can deploy your app across an organization.
If you use any of the Bolt frameworks to build Slack apps, make sure you have a version that supports organization apps.
| Bolt framework | Necessary version |
|---|---|
| Bolt for JavaScript | 3.0.0 |
| Bolt for Python | 1.1.0 |
| Bolt for Java | 1.4.0 |
Create a granular permissions app.
Configure a bot user. Your app's bot user represents the main way your users will interact with the app.
Head to your app config, scroll to the OAuth & Permissions sidebar, and add the necessary OAuth scopes.
The rest of app creation is the same as any other app. Follow the getting started guide if you'd like a more in-depth walkthrough.
In order to work across an organization, your app needs to be prepared for users and channels that span multiple workspaces.
You'll likely want to map users in Slack to users in your system.
If your app already stored some local IDs from a workspace that subsequently merged into an Enterprise org, the translation layer will continue to work as it did before.
For more insight into working with users in Enterprise organizations, check out the guide to single-workspace Enterprise apps.
Your odds of encountering a Slack Connect channel are high when developing an app for Enterprise. These channels are shared between one or more workspaces or organizations.
When you develop your app, decide which features should work with Slack Connect channels.
Once you've done that, remember to determine the type of conversation you're working with before you perform an action. Call the conversations.info method if you need to determine what kind of channel, DM, or MPDM you're dealing with.
Keep all these considerations in mind when building your app. Then continue on to learn how to install your organization-wide app.
To deploy your app across an Enterprise organization, you'll need to make your app installable by an Org Admin.
When an Org Admin installs your app across the entire organization, it is not added to any workspaces in the organization. The Org Admin must do this later, but they can add your app to several workspaces at once.
Like other Slack apps, organization-wide apps can be installed either via the UI from the app config page, or via the OAuth flow.
An app installed via app config will generate the organization-wide token automatically, whereas an app installed via OAuth will require a handshake to succeed in order to programmatically generate the token.
Both installation methods provide the token your app will use to interact with the Slack platform APIs. Regardless of how your app is installed, the organization-wide token behaves the same and requires the same changes to how your app is developed.
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 likely the most straightforward way to install the app.
Select Private Distribution from the Manage Distribution section in the app config sidebar. Enabling private distribution lets your app gain access to all of the workspaces in an organization.
You'll want to specify within your app config that your app may be installed across an entire Enterprise organization:
Add any bot scope, such as team:read. A bot scope is required for the next step to be available.
In the Org Level Apps section in the sidebar, select Opt-In, then select Yes, Opt-in at the confirmation prompt.
In the Install App section, select Install to Organization. Once installed, you'll be able to see new org tokens.
Your app can now be installed by an Org Admin or Owner at the organization level, rather than the individual workspace level. For more information about how to add apps to workspaces from your Enterprise Grid organization, refer to Manage apps on Enterprise Grid.
If you plan on making your app available for other organizations to install, or to list it in the App Directory, it is recommended that you follow the OAuth flow.
When an Org Admin installs your app across the entire organization, it will not yet be installed to any workspaces in the organization. Therefore, once you have completed the OAuth flow, you'll likely want to redirect an installing Admin back to a modal that will allow them to add the app to individual workspaces. For example:
https://app.slack.com/manage/ORG_ID/integrations/profile/APP_ID/workspaces/add
You need to determine whether the installation happened on an organization, as opposed to an individual workspace.
In order to do that, look for the is_enterprise_install boolean field in the oauth.v2.access method response:
{
"ok": true,
"access_token": "xoxb-XXXX",
"token_type": "bot",
"scope": "identify,users:read",
"bot_user_id": "W123ABC456",
"app_id": "A123ABC456",
"team": null,
"enterprise": {
"id": "E123ABC456",
"name": "Jesse Slacksalot"
},
"is_enterprise_install": true,
"authed_user": {
"id": "WXXXX",
"access_token": "xoxp-XXXX"
...
}
}
You'll want to consider redirecting your installer after OAuth for your organization-wide app, since the app won't actually be added to any workspaces yet. Consider redirecting to a modal that adds the app to workspaces, so that you can remind the installing Admin that they still need to do so:
https://app.slack.com/manage/ENTERPRISE_ID/integrations/profile/APP_ID/workspaces/add
For the most part, APIs at Slack work the same with all apps -- whether with an app that's deployed to an entire Enterprise organization or a single-workspace app. There are exceptions, however.
team_id parameter Since your app's token now can represent installations in many workspaces, some API methods will require a team_id parameter to indicate which workspace to act on.
You may have certain installations of your app that are on a single workspace, while other installations are deployed across entire organizations. A safe option is always pass a team_id parameter to these methods. If your token is a single-workspace installation, the team_id parameter will be accepted, but ignored.
Here's the full list of methods that require a team_id parameter when used by an organization-wide app:
You can call API endpoints that do not use a team_id parameter, but the behavior may be inconsistent.
For example, you can call the conversations.read method to retrieve information from channels that are shared across multiple workspaces within the organization using an org token, even if the app is not deployed to any workspaces within the org. However, if a channel only exists on a single workspace, the app will fail to retrieve any information and return a team_access_not_granted error instead.
context_team_id field You may also come across the context_team_id field in your org-wide travels.
We use this field behind the scenes to resolve which channels come from which workspaces within the organization, and what roles and preferences are applied to those channels. For all channel types, this field represents the perspective through which the viewing user is accessing the channel. Let's look at an example.
Let's say there is an Enterprise Grid instance called Middle Earth. Within that instance, there are two workspaces: Rohan and Gondor. You are a user in the Gondor workspace.
team_id field.context_team_id field.This field is used in outgoing dispatches only (such as Block Kit actions and other similar events); that is, it's not a field you'll be supplying to an API method call. We just wanted you to be aware of it and what it's used for in case it shows up in your logs! However, you can optionally supply this same information by using the client_context_team_id field when calling any API method that requires the channel argument. A couple examples are the chat.postMessage or chat.update API methods.
Event payloads now contain info on the authorizations that they apply to.
You'll see the is_enterprise_install boolean inside the authorizations object. This boolean tells you whether the event is being sent to an organization-wide installation of your app.
{
"token": "XXYYZZ",
"is_ext_shared_channel": false,
"team_id": "T123ABC456",
"api_app_id": "A123ABC456",
"event": {...},
"type": "event_callback",
"event_id": "Ev123ABC456",
"event_time": 1234567890,
"authorizations": [
{
"enterprise_id": "E324567",
"team_id": "T423567",
"user_id": "W43567",
"is_bot": false,
"is_enterprise_install": true
}
]
}
The authorizations object is truncated at a single installation. If you're not sure which installations have the ability to see the event, call the apps.event.authorizations.list method to get a full installation list.
There are events and methods to help you keep track of which workspaces within an organization-wide deployment your app actually has access to.
Two Events API events indicate to you when your organization-wide app has gained or lost access to a new workspace within your org:
Subscribe to these events to have an up-to-date list of workspaces to monitor and act in.
In addition, you can now use the auth.teams.list method to obtain a full list of workspaces your organization-wide app has been approved for. Call the method with your token acquired from installing your app on an Enterprise org.