Skip to main content

Legacy OAuth scopes

OAuth scopes let you specify exactly how your app needs to access a Slack user's account. As an app developer, you specify your desired scopes in the initial OAuth authorization request. When a user is responding to your OAuth request, the requested scopes will be displayed to them when they are asked to approve your request.

Slack's system of OAuth permission scopes governs usage of Slack apps and their use of the Web API, Events API, RTM API, Slash Commands, and incoming webhooks.

A screen showing the requested scopes during an OAuth request

Types of Scopes​

Slack uses scopes that refer to the object they grant access to, followed by the class of actions on that object they allow (e.g. file:write). Additionally, some scopes have an optional perspective which is either user, bot, or admin, which influences how the action appears in Slack (e.g. chat:write:user will send a message from the authorizing user as opposed to your app).

The list of objects includes files, search, chat, and reactions, along with many other objects in Slack.

There are currently only three classes of action:

  • read: Reading the full information about a single resource.
  • write: Modifying the resource in any way e.g. creating, editing, or deleting.
  • history: Accessing the message archive of channels, DMs, or private channels.

For example, to request access to the list of channels on a workspace and the ability to send messages to those channels as a bot, your app would request channels:read chat:write:bot.

OAuth Scopes to API methods​

admin.analytics:read

admin.app_activities:read

admin.apps:read

admin.apps:write

admin.barriers:read

admin.barriers:write

admin.conversations:manage_objects

admin.conversations:read

admin.conversations:write

admin.invites:read

admin.invites:write

admin.roles:read

admin.roles:write

admin.teams:read

admin.teams:write

admin.usergroups:read

admin.usergroups:write

admin.users:read

admin.users:write

admin.workflows:read

admin.workflows:write

app_configurations:read

app_configurations:write

assistant:write

authorizations:read

bookmarks:read

bookmarks:write

calls:read

calls:write

canvases:read

canvases:write

channels:history

channels:join

channels:read

channels:write

channels:write.invites

channels:write.topic

chat:write

connections:write

datastore:read

datastore:write

dnd:read

dnd:write

emoji:read

files:read

files:write

groups:history

groups:read

groups:write

groups:write.invites

groups:write.topic

hosting:read

im:history

im:read

im:write

im:write.topic

links:write

lists:read

lists:write

mpim:history

mpim:read

mpim:write

mpim:write.topic

pins:read

pins:write

reactions:read

reactions:write

reminders:read

reminders:write

remote_files:read

remote_files:share

remote_files:write

search:read

search:read.public

stars:read

stars:write

team.billing:read

team.preferences:read

team:read

tokens.basic

triggers:read

triggers:write

usergroups:read

usergroups:write

users.profile:read

users.profile:write

users:read

users:read.email

users:write

OAuth Scopes to Events API methods​

OAuth scopes also govern subscriptions to event types in the Events API.

Slack app scopes​

If you're building a Slack app, you will also encounter three other scopes.

  • incoming-webhook - requesting this scope during the authentication process allows workspaces to easily install an incoming webhook that can post from your app to a single Slack channel.
  • commands - similarly, requesting this scope allows workspaces to install slash commands bundled in your Slack app.
  • bot - request this scope when your Slack app includes bot user functionality. Unlike incoming-webhook and commands, the bot scope grants your bot user access to a subset of Web API methods, the RTM API, and certain event types in the Events API.

Special scopes​

Additionally, Slack supports the following special scopes:

  • identify : Allows applications to confirm your identity.
  • client: Allows applications to connect to slack as a client, and post messages on behalf of the user.
  • admin: Allows applications to perform administrative actions, requires the authed user to be an admin.

Working with Scopes​

When making the initial authorization request, your application can request multiple scopes as a space or comma separated list (e.g. teams:read users:read).


https://slack.com/oauth/authorize?
    client_id=...&
    scope=team%3Aread+users%3Aread

When using the Slack API you can check the HTTP headers to see what OAuth scopes you have, and what the API method accepts.

$ curl https://slack.com/api/files.list -H "Authorization: Bearer xoxb-abc-1234" -I
HTTP/1.1 200 OK
x-oauth-scopes: files:read, chat:write, chat:write.public
x-accepted-oAuth-scopes: files:read

x-oauth-scopes lists the scopes your token has authorized. x-accepted-oAuth-scopes lists the scopes that the action checks for.

Please note that certain scopes cannot be asked for in combination with each other. For instance, you cannot request both the bot scope and the client scope. When users arrive at an authorization page requesting invalid scope combinations, they'll see an ugly error stating something to this effect:

    "OAuth error: invalid_scope: Cannot request service scope (bot) with deprecated scopes"

Deprecated Scopes​

The following scopes are deprecated and their use is strongly discouraged:

  • read
  • post
  • client

Alternatives to the read scope​

This scope allows apps to read and inspect a wide range of data types.

Analyze which types of data your app needs and locate the accompanying scope in our scope catalog.

For instance, if you need to read public channel history, request channels:history. If you need to read data about public channels, request [channels:read].

You'll find a scope corresponding to almost all types of data you'll encounter on the Slack platform.

Alternatives to the post scope​

This scope allows posting messages into Slack.

Create a Slack app and request the chat:write scope to use chat.postMessage to send messages to channels.

Alternatives to the client scope​

This scope allows an app to retrieve all workspace events in real time.

We recommend using a combination of relevant scopes with the Events API to retrieve just the events your app needs.

If you must use the RTM API, you must use the classic bot scope and token model with rtm.connect instead.