Working with workspace tokens
The developer preview for workspace apps has ended. Weβre taking the components of workspace apps and bringing them in phases to existing as well as new apps.
You are welcome to install workspace apps as internal integrations or distribute them to other workspaces, but we won't accept them as submissions for the Slack app directory going forward.
Using workspace tokens isn't recommended unless you've already built an app using them. New workspace apps may no longer be created.
Workspace tokens represented your Slack app's ongoing relationship and agency with a specific Slack workspace. This document covers:
- What workspace tokens can't do
- A different permissions model for workspace tokens
- Getting started fresh
Methods, events, and features that supported workspace tokens were stamped with this mark: workspace
And in case you're on the lookout, here's some other important documentation related to workspace apps:
- Permissions API
- Rotating and refreshing credentials
- OAuth permission scopes
- Web API methods supporting workspace tokens
Workspace tokens can't do that on Slack
In general, workspace-token-based Slack apps cannot do the following:
- Become distributed in the app directory.
- Contain a bot user β workspace tokens use a different model of permissions than bot tokens and user tokens.
- Connect to the RTM API β it's just not possible or practical with this permission model. Please use the Events API for near-real-time delivery instead.
- Incoming webhooks aren't part of the new Slack app model.
- Some functionality made possible through impersonating the authenticating user, like creating and inviting users to channels, is no longer possible.
Reminder: don't use workspace tokens unless you've already built an app using them.
A different permission model
Workspace apps operated on a different permission model that was more workspace-centric and context-centric than the original model.
Once installed with your selected base-level permissions, your app could be added to channels, direct messages, and other conversation types as directed by the workspace's members and administrators.
The Permissions API covers what you need to know about determining your token's current state and requesting progressive permissions.
One token to mind
At installation, you received a token representing everything your app could do with the installing workspace.
Since workspace app access tokens had so much power, they were typically short-lived. Slack granted a long-lived refresh token so that your app could refresh and rotate its token programmatically.
How do all the token types differ? See token types to compare.
Permissions API
The Permissions API allowed your app to interactively and progressively request additional permissions and capabilities. Read the Permissions API documentation for the full story.
Here were a few key points on how permissions were awarded to workspace apps:
Installed for an entire workspace
When these new kinds of Slack apps were first installed, it was done for an entire workspace. There was no special installing user.
Provisioned to channels, conversations, and resources
The permission scopes granted to your app were granted within the context of specific resources, channels, or conversations.
Often those permissions were narrow β maybe just a DM with 1 or 2 users. Maybe just read and write access to a single public channel. Or maybe your app had permission to understand the wider universe of the whole workspace.
One access token per workspace
All workspace permissions were encoded in a single access token. This access token could do anything your app has permission to do within the context of a single workspace.
Installing workspace apps
Workspace apps could be installed via two approaches:
- Installing your app to your own workspace through the guided App Management UI
- Installing your app to your own workspace using OAuth 2.0
- With the new permission model, some responses to token acquisition methods differed from legacy Slack app OAuth.
Installing with OAuth 2.0
Slack OAuth 2.0 implementation remained largely unchanged for workspace apps. If you're new to Slack's OAuth sequence or OAuth 2.0 in general, we recommend reading our OAuth guide to understand the sequence of steps involved.
- First you, or Slack, send a user to Slack's authorization end point:
https://slack.com/oauth/authorize
with the appropriate parameters. - Users determine whether they want to install the app given the permissions it is requesting
- (new) Users determine to which resources they want to give the app access: public channel(s), a direct message, a group DM, workspace user data, etc.
- Slack sends the user back to the redirect URI you registered in your app's management console, along with a short-lived verification
code
value - You send a request to
https://slack.com/api/oauth.access
with a few parameters, including thatcode
value we sent you in the last step - Slack returns a response with two tokens: a token beginning with
xoxa-2-
, your access token encoding your current permission level with that workspace; and a refresh token beginning withxoxr-
, used to refresh the access token when it expires. For more info on token rotation, check out the page on rotating and refreshing credentials.
As with all of our OAuth flows, apps could be installed multiple times by the same user or different users. In the workspace model, apps were installed onto the whole workspace but the installing user decided which resources to provision to the Slack app.
There were other ways for users to elevate the permissions and resources afforded to your app. Read about them in the Permissions API.
OAuth installation response
When negotiating workspace tokens with oauth.token
, you'd receive JSON payloads differing significantly from the typical response found in oauth.access
.
Dwell on this little bit of well-intentioned complexity:
{
"ok": true,
"access_token": "xoxa-2-access-token-string",
"token_type": "app",
"app_id": "A012345678",
"app_user_id": "U0AB12ABC",
"installer_user_id": "U061F7AUR",
"authorizing_user_id": "U061F7AUR",
"workspace_name": "Subarachnoid Workspace",
"team_id": "T061EG9Z9",
"scopes": {
"app_home": [
"chat:write",
"im:history",
"im:read"
],
"workspace": [],
"channel": [
"chat:write"
],
"group": [
"chat:write"
],
"mpim": [
"chat:write"
],
"im": [
"chat:write"
],
"user": []
},
"single_channel_id": "C061EG9T2"
}
This structure communicated a short story:
- An access token was awarded or refreshed on the workspace identified by
T061EG9Z9
("Subarachnoid Workspace") for your Slack app identified by the IDA012345678
. - The user who originally installed the app was the same user currently performing the authorization flow, user
U061F7AUR
. - The user approved the app for the
chat:write
scope, but access was only granted to a single public channel resource,C061EG9T2
. - The app was automatically awarded the ability to read, write, and peruse the history of its conversation with the installing user in its
app_home
. Subscribe to these messages using the Events API eventmessage.app_home
.
oauth.token
response field guide
access_token
- Your workspace token that begins withxoxa-2
. It can be very long.token_type
- You'll seeapp
here. Workspace tokens were once known asapp
tokens. Maybe someday this value will becometeam
.app_id
- This is the unique ID for your whole Slack app.app_user_id
- This is the user ID of your app. It's a user! It's an app! It's a user! It's an app! The user ID is unique to the workspace installing it.installer_user_id
- This is the user ID of the user that originally installed this app.authorizing_user_id
- This user ID belongs to the user currently undergoing the authorization process.workspace_name
- This is what the workspace calls itself.team_id
- This is the unique ID for the workspace.- This field is no longer available. Usepermissions
apps.permissions.info
to look up all of your app's permissions for this workspace instead.scopes
- the OAuth scopes awarded to your app in this particular installation attempt.single_channel_id
- if this app is approved for a single channel, that channel will be listed here. See single channel authorizations for more info.
Use apps.permissions.info
to look up your app's permissions on the fly.
Scopes categorized by resource
Scopes were grouped by resource type:
app_home
- your app's direct message conversation with the installer of this appteam
- workspace-level permissions assigned to your appchannel
- public channelsgroup
- private channelsmpim
- multi-member direct messagesim
- direct messagesuser
- permissions to work with or as specific users
The Permissions API describes in more detail how resources and scopes work together to enforce what your app can do.
Single channel authorizations
To request access to only a single channel, add single_channel=true
to the querystring you generate for the oauth/authorize
step of the OAuth flow.
Users will be asked to approve your app's requested scopes just for a single channel they choose. When the approval process is complete, the response to oauth.token
or oauth.access
will contain a single_channel_id
field noting the channel resource.
Repeating this process multiple times on the same workspace adds additional channel grants to your app, one by one.
Use this approach with the chat:write
and channels:history
scopes to effectively install a bot into a single channel.
Ask for only chat:write
just to post notifications into a single channel, turning chat.postMessage
into a replacement for incoming webhooks.
New permission-oriented app events
These app events were available for the Events API as part of the new Permissions API.
resources_added
- your app was granted access to resources (like specific channels, a collection of channels, specific IM, emoji, etc.)resources_removed
- access that your app had to a set of resources has been removedscope_granted
- your app was given access to a specific scopescope_denied
- your app was denied access to a specific scopemessage.app_home
- Dispatches when a user sends your app a message via their direct message-like App Home interface.
Incoming webhooks
Incoming webhooks were not supported by workspace apps.
RTM API
Workspace apps can't connect to the RTM API. There's no permission scope in the progressive model that grants the level of access required to connect to Slack's message server. For near real time event delivery, you must use the Events API.
How do I migrate my existing Slack app?
We don't plan to migrate existing Slack apps to the workspace token model. Many features first available to workspace apps will become available to classic Slack apps in the coming months.
How do I distribute my workspace app?
Install a workspace apps into any workspace using OAuth 2.0. Workspace apps cannot be listed in the Slack app directory.
Thanks for trying our developer preview for workspace apps! We welcome your feedback. Email us at feedback@slack.com.