Organization-wide app overview

If you want your Slack app to reach the most people, build an app that can be deployed across an Enterprise Grid organization. Organization-wide apps have the potential for effortless, widespread deployment—by some of the largest users of Slack in the world.

If you want more details on building a single-workspace app that works on Enterprise, check out our other documentation here.

If you want to start with a refresher on what apps can do generally, look no further than our start guide.

Otherwise, read on for more details on how to deploy an app across an entire Grid organization.

What's an organization-wide app?

Enterprise organizations are able to combine multiple workspaces in one organization. You can read more on the model of Enterprise to get a better sense of what to expect.

Until the release of organization-wide apps, supporting apps on Enterprise Grid meant apps had to be installed separately on each workspace. This was difficult for administrators to maintain and for developers to manage, since each app required a separate OAuth token for each workspace.

An organization-wide app is an extension of a regular Slack app—the difference is that it can be deployed across an entire organization. These apps are installed once, at the organization level, and have a single token that represents the permissions for the app on many workspaces.

Here are some of the benefits for your users:

  • Org Admins will now be able to distribute apps easily across all workspaces.
  • Pre-approved apps can be automatically installed when a workspace is created.
  • Users only have to authenticate with an app once for all workspaces that have access to the app.
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 pretty similar to apps installed on a single workspace, there are a few changes to be aware of. Read on for a host of information on how to ready your app for organization-wide deployment.

Preparing for organization-wide deployment

Read our walkthrough for making your app Enterprise-ready. You'll find hints on how your app should handle users and channels that span multiple workspaces.

If you use Bolt frameworks or SDKs to build Slack apps, make sure you have a version that supports organization apps. Check the Bolt version requirements list.

Changes: OAuth & Installation

Once your app is successfully scaled to handle Enterprise organizations, check out this list of changes to the pattern of OAuth & Installation for an app across an Enterprise org.

Changes: Using APIs

Now that your app is successfully deployed on an Enterprise organization, you can read up on changes to APIs and events.

Migration tips

If you want some quick tips on turning an single-workspace Enterprise app into an org-ready one, look no further.

One special call-out: Webhooks are not supported with organization-wide apps. Use our modern suite of messaging tools instead.


Our reference page gives a grab-bag of samples: event payloads, API calls, OAuth installation, and methods that use team_id with organization-wide app tokens.

You can call API endpoints that do not use team_id—but the behavior may be inconsistent.

For example, you can call the API 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 will instead return a team_access_not_granted error.

We recommend reading up on using APIs with organization-wide apps for more details.

Recommended reading