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.

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 effects 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 team 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

Oauth Scope	Associated Methods
channels:write	channels.archive channels.create channels.invite channels.join channels.kick channels.leave channels.mark channels.rename channels.setPurpose channels.setTopic channels.unarchive
channels:history	channels.history
channels:read	channels.info channels.list
chat:write:user	chat.delete chat.postMessage chat.update
chat:write:bot	chat.postMessage chat.update
dnd:write	dnd.endDnd dnd.endSnooze dnd.setSnooze
dnd:read	dnd.info dnd.teamInfo
emoji:read	emoji.list
files:write:user	files.comments.add files.comments.delete files.comments.edit files.delete files.revokePublicURL files.sharedPublicURL files.upload
files:read	files.info files.list
groups:write	groups.archive groups.close groups.create groups.createChild groups.invite groups.kick groups.leave groups.mark groups.open groups.rename groups.setPurpose groups.setTopic groups.unarchive
groups:history	groups.history
groups:read	groups.info groups.list
im:write	im.close im.mark im.open
im:history	im.history
im:read	im.list
mpim:write	mpim.close mpim.mark mpim.open
mpim:history	mpim.history
mpim:read	mpim.list
pins:write	pins.add pins.remove
pins:read	pins.list
reactions:write	reactions.add reactions.remove
reactions:read	reactions.get reactions.list
reminders:write	reminders.add reminders.complete reminders.delete
reminders:read	reminders.info reminders.list
search:read	search.all search.files search.messages
stars:write	stars.add stars.remove
stars:read	stars.list
team:read	team.info
usergroups:write	usergroups.create usergroups.disable usergroups.enable usergroups.update usergroups.users.update
usergroups:read	usergroups.list usergroups.users.list
users:read	users.getPresence users.info users.list
users:write	users.setActive users.setPresence

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 teams to easily install an incoming webhook that can post from your app to a single Slack channel.
• commands - similarly, requesting this scope allows teams 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.

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?token=abcd -I
HTTP/1.1 200 OK
X-OAuth-Scopes: files:read, chat:write:bot
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: Allows applications to read any messages and state that the user can see.
• post: Allows applications to write messages and create content on behalf of the user