Slack app scopes are the permissions your app requests when someone installs it. Each scope unlocks specific API methods and events, and anything you don't request is blocked. Pick too few and your app fails with missing-scope errors. Pick too many and admins refuse the install. This guide covers what scopes are, how bot and user tokens differ, which scopes an AI assistant usually needs, and how to change them later without breaking your setup.

TL;DR

Scopes are granular permissions attached to an OAuth token. Slack's scope reference lists over 100 of them, grouped into areas such as channels, chat, files, admin and assistant.
Use a bot token for an always-on assistant. It belongs to the app, not to a person, so it keeps working when a teammate leaves.
Start with the minimum: usually app_mentions:read, chat:write and the history scope for the conversations the assistant should read.
Adding a scope later normally means reinstalling or re-authorizing the app, so plan your list before you ship.
Avoid admin scopes unless you truly need them. They are a common reason IT teams reject an app.

What Slack scopes actually are
Bot tokens vs. user tokens
Scopes an AI assistant typically needs
Scope creep and the principle of least privilege
Changing scopes after launch
Troubleshooting missing-scope errors
Our perspective: scopes as a design choice
Running an assistant on Slack without the setup work
Related reading
FAQ
Sources

What Slack scopes actually are

According to Slack's documentation, OAuth scopes are the permission boundaries of a Slack app. They define what the app may do: read messages, post content, manage workspace settings. An app cannot touch data it has not been explicitly authorized to reach.

Think of scopes as the keys on a ring. The token is the ring itself, and each scope is one key. Slack describes tokens as the keys to the platform that tie together all the scopes and permissions your app has obtained.

The flow works like this:

You declare the scopes your app wants.
A person installs the app through OAuth 2.0 and sees the list of requested scopes.
When they approve, Slack issues an access token carrying exactly those permissions.
Every API call is checked against the token's scopes.

The naming is consistent: resource:action. So channels:history is about reading message history in public channels, chat:write is about sending messages, and users:read is about viewing people in a workspace. Once you see the pattern, the long list becomes much easier to scan.

Bot tokens vs. user tokens

This is the decision that shapes every other scope choice. Slack's token types page describes the main two: bot tokens for automated tasks, and user tokens for actions performed on behalf of an individual.

	Bot token	User token
Acts as	The app itself	A specific person
Survives staff changes	Yes	No, it breaks if the account is deactivated
Best for	Always-on assistants, notifications, workflows	Actions that must appear as the person, or need that person's access
Typical risk	Over-broad bot scopes	Tied to one human's access and credentials

The research behind this guide is blunt on the practical side: bot tokens are bound to the app, so if a team member leaves, an assistant on a bot token stays connected. User tokens are powerful but brittle, because a password change or deactivation can break them.

Some scopes work with both. For example, chat:write lets you send messages as your Slack app and supports both bot and user tokens. Others are restricted. The admin scope supports user tokens only, which is one more reason it is awkward for automated assistants.

If you are designing something more involved than a single assistant, such as agents that touch CRMs or marketing systems, it helps to decide early which actions must be automated and which must be performed as a person. Teams that want help mapping that out can look at custom AI agent development for a sense of how those systems are scoped.

Scopes an AI assistant typically needs

Slack's reference notes that for AI assistants, common scopes include chat:write for sending responses, app_mentions:read for noticing when someone calls the bot, and assistant:write, which lets the app function as a formal App Agent in Slack. Those come from the official scopes list.

Here is a practical starter set, ordered from most to least universal:

app_mentions:read: lets the assistant see messages where it is @mentioned. For a bot people summon in channels, this is the minimum for listening.
chat:write: lets it reply. Without it, the assistant can think all it likes and never answer.
im:history: reads direct messages sent to the assistant, needed for one-to-one conversations.
channels:history: reads messages in public channels. Add it only if the assistant must follow a conversation, not just respond to mentions.
assistant:write: for apps using Slack's formal assistant experience.

Notice what is missing: admin, anything about managing users, and anything about files unless you need it. A reply-only assistant has no business with those.

The background material for this article gives the clearest example: if you want your assistant to read messages, it needs channels:history or im:history. Without the right scope, Slack's API responds with an error even if your code is perfect.

Matching scopes to jobs

A useful exercise is to write the assistant's jobs as sentences, then map each to a scope.

"Answer when someone mentions it" maps to app_mentions:read and chat:write.
"Answer in DMs" maps to im:history and chat:write.
"Summarize a channel on request" maps to channels:history, scoped by where you invite it.
"Look up who someone is" maps to users:read.

If a scope has no sentence behind it, delete it from the request.

Scope creep and the principle of least privilege

Scope creep happens when developers request extra scopes "just in case." It is poor practice for security and for trust. Slack's scopes documentation explains why granularity matters: with narrow, resource-specific permissions, a compromised app can only reach what it was authorized for.

There is a human side too. Every scope on the install screen is a question to the person installing: do I trust this app with this level of access? An admin-level request raises the most friction, especially for enterprise users, and IT departments will often block it. Being judicious with scopes improves the odds that people finish the install.

A quick audit routine:

List every scope in your app config.
For each, name the exact API method or event that needs it. Slack's scope pages list compatible methods, for instance on the chat:write page.
Remove any scope you cannot connect to a feature you ship.
Re-run the audit whenever you add a feature.

Slack has also been moving away from older, broad permissions. The legacy bot scope, for instance, applies only to legacy bot tokens. New apps should use the granular scopes instead.

Changing scopes after launch

This is where people get caught. Adding a new scope generally means the app must be re-authorized in the workspace, so you cannot quietly patch permissions in for existing installs. Slack's authentication overview is the place to confirm the current behavior for your app type.

Plan for it:

Update the scope list in your app configuration.
Reinstall or re-authorize the app in the workspace so a new token is issued.
Replace the stored token wherever your app or assistant uses it.
Test the feature that needed the scope.

If you're connecting an assistant to a team Slack, tell the workspace admin first. A sudden re-authorization prompt with a longer scope list looks suspicious without context.

Token rotation

Tokens can also expire. Slack's token rotation guide says that without rotation an access token never expires, while with rotation it expires every 12 hours and a refresh token is used to get a new one. Rotation limits the damage of a leaked token, and it makes your integration easier to audit. The cost is that your app must handle refreshes correctly.

Troubleshooting missing-scope errors

When something fails, work through this order:

Read the error. Slack's responses typically name the problem. A missing-scope response is different from a channel-access problem.
Check the method page. Each method documents which scopes it needs. Compare with your token's scopes.
Confirm the token type. A scope you added under user scopes will not appear on the bot token, and the reverse is also true.
Reinstall. Changing the config does not change an already-issued token.
Check conversation membership. A bot may have the right scope and still be unable to read a channel it has not been invited to.

The frustrating case is a workflow tool with hard-coded scopes that don't match what a given action needs. If you use a no-code automation connector, check whether it lets you customize scopes or only uses a fixed list. If it is fixed, a custom app with your own token may be the cleaner route.

Our perspective: scopes as a design choice

We look at Slack scopes from the point of view of a managed, always-on assistant. Three beliefs shape how we think about them.

First, an assistant is a teammate, not a script. It should have a defined role and permissions that match. When the permissions fit the role, people trust it, and trust is what gets an assistant used daily rather than abandoned after a week.

Second, the install screen is part of the product. Our audience ranges from non-technical users to developers, and most of them have never read a scope list. A short, understandable list is a feature. Long lists make people stop and email IT.

Our perspective: scopes as a design choice — overview diagram

Third, setup should not require reading API docs. OpenClaw is a capable open-source assistant, but configuring it yourself means handling servers, tokens and updates. That is the barrier we built ClawBase to remove. You still deserve to understand what you are granting, which is why we recommend learning the basics in this guide even if you never write an OAuth handler.

Our practical advice: begin with mention and reply scopes, add history scopes only when you can name the feature that needs them, and review the list every time you add a skill. Treat each scope as something you may have to justify to a colleague.

> *— Iosif Peterfi*

Running an assistant on Slack without the setup work

If you want an always-on assistant in Slack without managing servers, ClawBase hosts OpenClaw for you on a dedicated, encrypted cloud server, with one-click deployment and connections to Telegram, Discord, Slack and WhatsApp. It also includes persistent memory, access to over 50 AI models and daily encrypted backups, with no sysadmin skills required.

Plans on the pricing page are:

Plan	Monthly	Annual
LITE	$16 per month	$199 per year
PRO	$33 per month	$399 per year
MAX	$66 per month	$799 per year

The entry plan includes a 7-day free trial, and you can pay by credit card or cryptocurrency.

FAQ

What is the difference between bot scopes and user scopes?

Bot scopes are attached to a bot token, which belongs to the app and acts as the app. User scopes are attached to a user token, which acts on behalf of the person who authorized it. For an always-on assistant, bot scopes are usually the better choice, since they do not depend on one person's account staying active.

Do I need to reinstall my Slack app after adding a scope?

Generally yes. A new scope has to be approved through the OAuth install flow, which issues a token that carries it. Tokens you already hold keep their old permissions, so update the stored token after reinstalling and test the feature again.

Which scopes does a Slack bot need to reply to messages?

At a minimum, chat:write to post replies. To know when it is called, add app_mentions:read, and im:history if people will message it directly. Add channels:history only if the bot must read ongoing channel conversation.

Why would an IT admin reject my Slack app?

The most common cause is a scope list broader than the app's purpose, especially admin-level permissions. Every scope appears on the install screen, so an unexplained request for wide access invites a no. Trim the list to what the features need and explain each scope in your install notes.

Slack App Scopes: How to Choose the Right Permissions