OAuth & Installation for organization-wide apps

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; they can add your app to several workspaces at once.

Refresher: Installing Slack apps

As a reminder, Slack apps can be installed either via the UI from the app config page, or via the OAuth flow.

The same is true for organization-wide apps. 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.

Installing organization-wide apps

In general, 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 gain access to all of the workspaces in an organization. To enable private distribution, select Private Distribution from the Manage Distribution section in the app config sidebar.

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. You can get a refresher on the OAuth process here.

As mentioned earlier, once 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/{your-org-id}/integrations/profile/{your_app_id}/workspaces/add

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. Refer to Using APIs with organization-wide apps for more details.

Determining installation type during the OAuth flow

The only additional consideration for OAuth with an organization-wide app is that 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 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": "Sir Not-Appearing-In-This-Film"
    },
    "is_enterprise_install": true,
    "authed_user": {
        "id": "WXXXX",
        "access_token": "xoxp-XXXX"
            ...
    }
}

Opting in to organization-wide installation

First, you'll want to specify within your app config that your app may be installed across an entire Enterprise organization.

In the Org Level Apps section in the sidebar, select Opt-In, then select Yes, Opt-in at the confirmation prompt.

You'll need a bot scope such as team:read in order for the Opt-In button to be enabled (this scope won't actually be used).

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.