Migrating from single-workspace to organization-wide deployment

Apps deployed across an Enterprise organization are installed somewhat differently and have slightly different API usage.

Those other pages cover what's new and differs from single-workspace apps that you might've built. But how do you migrate an existing single-workspace app (one that's ready for Enterprise) into an organization-wide deployment?

Read on for tips to keep in mind to make the transition from single-workspace to organization graceful.


Opt into organization-wide deployment

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.

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.


Use a minimum version of the SDKs

If you make use of Bolt frameworks or other SDKs to build Slack apps, make sure your version supports organization-wide apps.

To use Bolt for JavaScript, you'll need version 3.0.0 or higher.

To use Bolt for Python, you'll need version 1.1.0 or higher.

To use Bolt for Java, you'll need version 1.4.0 or higher.

Check the other SDKs' individual documentation for version requirements.


Token storage

When your app turns from a single-workspace app into one that's deployed across an org, you may want to rethink the way you store tokens.

Previously, you might have stored one row in a database for each installation, and each row might contain a token.

Now, you can change your schema to reflect a one-to-many relationship between tokens and installations.

Alternatively, you can maintain the same one-to-one relationship and have rows for each installation and token, but you'll probably want to organize these with a sort key: the enterprise_id.


Tokens from previous installations

If your app is installed on an entire org, where previously it was installed for specific users and workspaces, you might still have thousands of existing user tokens. These tokens will continue to function after you become an organization-wide app.

After the app is installed on the organization, you'll be able to use a single organization-wide user token for any users that authenticate after that moment (or reauthenticate).

And don't worry: your existing paths to gain user tokens (like Sign in with Slack, or just a regular OAuth sign-in flow for users) will still work. Those permissions will each be added to your organization-wide user token, rather than creating a new token.

After an organization-wide deployment, all the workspaces where your bot was installed will automatically be accessible to the new organization-wide bot user token.

Your app does not lose access to workspaces or need to interrupt users. You can use the organization-wide bot user token for workspaces where your app had already been installed.


User IDs

If you previously had User ID translation ON in your Enterprise app, now is the time to turn it OFF.

Single enterprise user IDs are now available. There's no benefit to continuing to maintain local IDs. Use migration.exchange to obtain the new single IDs for any users that you have remaining local IDs for.


Scopes are inherited

When your app is install across an org, the scopes set during that installation pass down to each installation on individual workspaces within that org. Even if you pass different scopes during the OAuth redirect when you gain access to an individual workspace, you'll still receive only the scopes set during the organization-wide install.


Webhooks cannot be used

Webhooks aren't supported with organization-wide apps. Use chat.postMessage and our modern messaging suite of tools.


Chat.postMessage requires channel IDs

Usually, when you call the chat.postMessage method to post a message to Slack, you specify the channel using a channel ID.

If, however, you specified the channel using a channel name, the call from your organization-wide app will not succeed. You'll want to begin using channel IDs instead.


Apps for Enterprise administration aren't supported

Some Slack app features that are specifically designed for Enterprise administration—including Audit Logs, SCIM, and other Admin APIs—already work with Enterprise organizations, rather than individual workspaces.

You only need to install your app at the organization level to use these Admin APIs — You won't need to deploy your app across your org.