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, in addition to alleviating the problems with workspace-installed apps:
Organization-ready apps are installed once at the organization level, but an organization-ready app isn't automatically added to the workspaces in an organization nor does it enjoy any additional privileges by being installed at the organization level. Read more about this nuace below. The app has a single token that represents the permissions for the app on multiple workspaces and is authorized once for an entire organization using OAuth. Admins can then add it to workspaces in the organization without further authorization.
Sometimes apps are required to be organization-wide.
In the latter case, the apps are Slack-hosted, so we take care of the heavy lifting for you. For the former case, read on to learn what actions need to be taken to ensure your custom steps are available for use in Workflow Builder.
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 |
|---|---|
3.0.0 |
|
1.1.0 |
|
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 settings, 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-ready 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.
Organization-ready apps can be installed via the UI from the app settings page, via the OAuth flow, or via the CLI for workflow automation apps.
An app installed via app settings 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 settings is likely the most straightforward way to install the app.
First, navigate to OAuth & Permissions, scroll down to Scopes, and add any bot scope to your app, 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. This will be reflected in the app manifest like this:
"settings": {
"org_deploy_enabled": true,
...
}
The next part of installing the org-ready app differs between an Org Admin and non-admin users.
Requesting to install the app to an organization means that an app manager will receive a direct message from Slackbot to review the request. Approving a request to install to the org means the admin installs the app to the org, then further decides which workspaces to add it to. For more information about how to add apps to workspaces from your Enterprise Grid organization, refer to Manage apps on Enterprise Grid.
An app installed at the organization level and granted to one or more workspaces in the organization does not have any additional privileges compared to an app installed at the workspace level alone. Organization-ready applications do not need to be granted to all workspaces, and they in fact are not added to any automatically when they are org-installed. An Org Admin user can determine to which workspaces the app is granted from the admin dashboard. The advantage of installing at the organization level is the ability to have the app follow an organization policy, to simplify token storage, and the ability to share custom steps defined in app code for use in Workflow Builder.
The restrictions defined by which workspaces the app is added to carry through to which users will have access to the app's custom steps in Workflow Builder. Take for example Enterprise Fruit. Enterprise Fruit has three workspaces: Apple, Banana, and Cantaloupe. If an organization-ready app, FruitFly, is shared only with workspaces Apple and Banana, then users in Cantaloupe cannot access it or any custom steps belonging to it. Further, any workflows built using the custom steps from FruitFly cannot be accessed or used by users in Cantaloupe.
If you plan on making your app available for other organizations to install, or to list it in the Slack Marketplace, it is recommended that you follow the OAuth flow. This option is only available to apps that do not have custom steps.
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-ready 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 Deno-based workflow automations, deploying apps is done via the Slack CLI. Refer to Deploy to Slack in the workflow automation documentation for more details.
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-ready 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-ready 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-ready app has been approved for. Call the method with your token acquired from installing your app on an Enterprise org.