{"id":8413,"date":"2026-03-25T09:13:16","date_gmt":"2026-03-25T16:13:16","guid":{"rendered":"https:\/\/slack.dev\/?p=8413"},"modified":"2026-04-14T12:15:46","modified_gmt":"2026-04-14T19:15:46","slug":"introducing-optional-scopes-for-slack-apps","status":"publish","type":"post","link":"https:\/\/slack.dev\/introducing-optional-scopes-for-slack-apps\/","title":{"rendered":"Give users the power to choose: introducing optional scopes for Slack apps"},"content":{"rendered":"\n

When someone installs your Slack app, they’re making a trust decision. They’re saying: “Yes, I want this app, and I’m okay with it accessing these parts of my workspace.” But what happens when your app asks for permissions they’re not comfortable with? Too often, they just… don’t install it. And you never even get a chance to show them the value.<\/span><\/p>\n\n\n\n

That’s the problem optional scopes solve.<\/span><\/p>\n\n\n\n

The permission problem<\/span><\/h2>\n\n\n\n

OAuth scopes are how your Slack app declares what it needs access to. Historically, it’s been all or nothing. Users either accept every scope your app requests, or they walk away. For apps with a broad feature set, that can mean asking for permissions that only power a subset of features, which, honestly, can feel like a big ask for someone who just wants the basics.<\/span><\/p>\n\n\n\n

The result? Higher installation abandonment. Lower trust. Fewer users.<\/span><\/p>\n\n\n\n

Enter optional scopes<\/span><\/h2>\n\n\n\n

Optional scopes let you designate certain permissions as optional during app configuration. When a user installs your app, they see which scopes are required (non-negotiable for the app to function) and which are optional (needed only for specific features they may or may not want).<\/span><\/p>\n\n\n\n

Users get to make an informed choice. Your app gets installed more often. Everyone wins.<\/span><\/p>\n\n\n\n

Setting it up<\/span><\/h2>\n\n\n\n

There are two ways to mark scopes as optional:<\/span><\/p>\n\n\n\n

Via the App Management Page<\/b>
<\/b>Head to <\/span>Apps Settings<\/span><\/a> page and open your app’s OAuth & Permissions settings. You’ll see a checkbox next to each scope. Simply uncheck the ones you want to make optional. That’s it.<\/span><\/p>\n\n\n\n

Via App Manifest<\/b>
<\/b>If you manage your app configuration as code (and if you\u2019re not yet\u2014you probably should give it a go), add optional scopes to the new bot_optional<\/code><\/span> or user_optional<\/code><\/span> fields in your <\/span>oauth_config<\/span>:<\/span><\/p>\n\n\n\n

"oauth_config": {\n\t"scopes": {\n\t\t"bot": [\n\t\t\t"chat:write",\n\t\t\t"commands",\n\t\t\t"reactions:write"\n\t\t],\n\t\t"bot_optional": [\n\t\t\t"reactions:write"\n\t\t],\n\t\t"user": [\n\t\t\t"channels:history",\n\t\t\t"reactions:read"\n\t\t],\n\t\t"user_optional": [\n\t\t\t"reactions:read"\n\t\t]\n\t}\n}<\/code><\/pre>\n\n\n\n
Optional scopes must be a subset of your declared bot or user scopes respectively. Think of the required scopes as the full list, and optional scopes as the ones users can opt out of.<\/span><\/p>\n\n\n\n
Building an app that handles it gracefully<\/span><\/h2>\n\n\n\n
Here’s the important part: once you introduce optional scopes, your app needs to be ready for users who don’t grant them. You\u2019re giving users a choice, your app needs to respect it. An app that crashes or throws errors when an optional permission is missing defeats the whole purpose.<\/span><\/p>\n\n\n\n
If you’re building with the <\/span>Slack MCP Server<\/span><\/a>, some of this comes built in. MCP only exposes the tools a token has permission to use, which means your agent won\u2019t attempt actions it doesn\u2019t have access to in the first place. That reduces the need for manual scope handling in many cases.<\/span><\/p>\n\n\n\n
There are a few patterns you\u2019ll want to build into your app:<\/span><\/p>\n\n\n\n
    \n
  1.  Graceful degradation<\/b>
    <\/b>When a user hasn’t granted an optional scope, your API calls may return a <\/span>missing_scope<\/span> error. Catch these errors explicitly and respond gracefully. Maybe show a prompt explaining what the feature requires and how to enable it, rather than a broken experience.<\/span><\/li>\n\n\n\n
  2.  Token scope storage<\/b>
    <\/b>When a user completes the OAuth flow, the <\/span>oauth.v2.access<\/span> response includes the list of scopes that were actually granted. Store these. They’re your source of truth for what that user has authorized.<\/span><\/li>\n\n\n\n
  3.  Feature gating<\/b>
    <\/b>Before rendering a feature that requires an optional scope, check whether that scope is in the stored grant list. If it’s not there, hide the feature or show an upsell prompt \u2014 don’t let users hit a wall mid-workflow.<\/span><\/li>\n<\/ol>\n\n\n\n
    Think of optional scopes as progressive enhancement for your app. The core works for everyone; richer features unlock for users who opt in.<\/span><\/p>\n\n\n\n
    A note for workspace admins<\/span><\/h2>\n\n\n\n
    If your app is installed in organizations with app approval workflows, workspace admins have an important role here too. When approving an app, admins now control the superset of optional scopes their users can choose from.<\/span><\/p>\n\n\n\n
    Required scopes are auto-approved as always. Optional scopes show up as checkboxes. Admins decide which ones are on the table, and users can choose from within that set. This gives organizations fine-grained governance without blocking productivity which, as you can imagine, is a big deal for larger teams.<\/span><\/p>\n\n\n\n
    Admins can manage approvals from the App Management page or directly from the SlackBot DM request.<\/span><\/p>\n\n\n\n
    What users see<\/span><\/h2>\n\n\n\n
    From the end user’s perspective, optional scopes make the install experience feel more respectful. Instead of a take-it-or-leave-it list of permissions, users see a clear distinction between what the app needs and what it would like.<\/span><\/p>\n\n\n\n
    They’re in control.<\/span><\/p>\n\n\n\n
    As a developer, your job is to honor that choice. If a user opts out of an optional scope today, make it easy for them to enable it later if they change their mind. But don’t make opting out feel like a penalty.<\/span><\/p>\n\n\n\n
    Get started<\/span><\/h2>\n\n\n\n
    Optional scopes are available now. Here’s what to do:<\/span><\/p>\n\n\n\n