Go to Slack

Developer preview: Workspace-based Slack apps

Developer preview

Welcome to the workspace token-based Slack app developer preview, still under active development.

This is a preview of the next generation of Slack apps. We want Slack apps to be ever easier to discover, trial, install, and upgrade and this new token type and permission model is the vehicle to that future.

Read our announcement to learn more about our motivation behind these changes and the benefits delivered to users and developers.

Try it now

Create a developer preview app

Your workspace token-based Slack apps cannot yet be distributed to other teams via the directory. They're just for your personal enjoyment, development, and exploration. Stay tuned.

Take a ride with Lunch Train

We open-sourced Lunch Train and now it works with workspace tokens.

Lunch Train is a PHP app that helps teams plan lunch outings together.

  • Install LunchTrain 2.0 on your team now to experience progressive permissions for yourself and the new installation flow.
  • Clone slackapi/lunchtrain to understand how the sandwich is made and adapt it for your team's food, fun, or funky preferences.

There may be no free lunch but at least there's a free Lunch Train. All aboard!

Read the documentation

Workspace tokens that power these new Slack apps work just like you're used to. Except they don't, so you'll want to catch up with this fresh documentation:

Look for these notices amidst content about different types of tokens for workspace-token specific information:

This treatment appears on OAuth scopes and Web API methods that support workspace tokens. Let it guide your way.

Developer preview

This feature only applies to the workspace token-based Slack app developer preview, currently under active development.

What's new?

Workspace token-based Slack apps bring a number of refinements to the original model:

  • Workspace token-based Slack apps are installed on a team-level. Once installed on the team, the team owns the installation.
  • After installation, a workspace token-based Slack app can be added to public channels, private channels, direct messages, and other conversation types.
  • Your app is granted a single, potent access token per team that always reflects your app's current and full set of permissions and capabilities.
  • Upon installation, your app has the ability to open a direct message conversation with the installer of the app — an opportunity to let them know how your app works and offer a safe demo experience.
  • If the mood strikes you, your app may progressively ask for additional permissions as part of an interactive conversation experience, without requiring the heft of a full reinstallation flow.
  • Link deeply into Slack and conversations with your app.
  • Finally, the app is the bot and the bot is the app. Slack apps have a more user-like presence on Slack, like bot users of contemporary yore.

What's next

The launch of this developer preview is only the beginning.

Coming soon to a workspace token near you:

  • Permissions APIs improvements will expand permission upgrade requests to include asking for access to specific resources.
  • Enterprise Grid will gain support for app creation, installation, and of course, usage.
  • We'll enable Write methods like channel creation.

Longer term, we'll provide clarity around:

  • The migration plan. How will your existing apps migrate to workspace tokens? Good question.
  • Impersonation. How do workspace token-based apps work from the perspective of a specific user, when appropriate? What about Sign in with Slack
  • More methods, more permissions, more opportunities for user discovery.

For now, workspace token-based Slack apps aren't ready for distribution in the app directory.

Stay tuned

Keep track of where we're going:

Send us feedback! We love feedback! Email us at developers@slack.com.

Known issues

As with any nascent far-reaching platform feature, workspace tokens have a few bugs and unimplemented but planned features.

Feature Problem
Enterprise grid Workspace token-based Slack apps cannot yet be installed on or created within Enterprise Grid workspaces. If you're part of a Grid, create a test team to work with the developer preview.
Chat New! Workspace tokens now use the new chat:write scope. They used to use the vintage chat:write:user scope. Learn more.
Files New! Your workspace token-based app can read and write files with the files:read and files:write scopes. Learn more.
OAuth The oauth.token method will eventually be removed and the more typical oauth.access path now that it supports the workspace token flow.
OAuth resource_id attribute values in oauth.token responses aren't always strings or IDs. You may receive a channel ID like "C123456" or you might receive an integer like 0.
OAuth Workspace tokens cannot yet call the legendary auth.test method.
OAuth Workspace token-based apps' approved OAuth scopes are not listed in HTTP headers like X-OAuth-Scopes and X-Accepted-OAuth-Scopes and it's possible they never will be.
Documentation Some of the OAuth scopes listed as supporting workspace tokens do not actually support those tokens yet. Some methods claiming workspace token support don't support them yet. Personal experience will tell you for sure.

Find a new issue or have a question? Send us email to developers@slack.com.