Slack Permission Scopes Reference

Slack permission scopes define what actions an application can perform and what information it can access within a Slack workspace. When authorizing a Slack workspace connection, you grant Magentrix specific scopes that enable the integration to look up channels and users, send messages, and deliver record notifications. Understanding these scopes helps administrators make informed decisions about Slack Integration and address security or compliance questions.

This reference documents all permission scopes used by the Magentrix Slack App and Custom Slack Apps configured for Magentrix integration.

Understanding Slack OAuth Scopes

Slack uses OAuth 2.0 for authorization, with scopes defining the specific permissions granted during the authorization flow. Scopes follow a consistent naming pattern that indicates the resource type and access level.

Scope Naming Convention

Slack scopes follow the format resource:permission where:

• Resource: The Slack feature or data type being accessed (channels, users, chat, groups, im, mpim)
• Permission: The level of access granted (read, write, history)

For example, channels:read grants read access to channel information, while chat:write grants permission to send messages.

Token Types and Scope Assignment

Scopes are assigned to specific token types:

User Token Scopes: Permissions granted to user tokens that act on behalf of the authorizing user. Actions performed with user tokens appear as coming from that user.

Bot Token Scopes: Permissions granted to bot tokens that act as the application itself. Actions performed with bot tokens appear as coming from the app's bot user.

When you authorize a Slack workspace, Magentrix receives both a user token and a bot token, each with their respective scopes.

User Token Scopes

User token scopes enable Magentrix to perform actions on behalf of the user who authorized the connection. These scopes are essential for sending direct messages and accessing channel information.

channels:read

Description: View basic information about public channels in a workspace.

What This Enables:

• List public channels available in the workspace
• Retrieve channel names and IDs for automation task configuration
• Display channel options in Slack Message task dropdowns
• Identify which channels exist for message targeting

What This Does Not Enable:

• Read message content or history in channels
• Access private channels (requires groups:read)
• Modify channel settings or membership

channels:write

Description: Manage a user's public channel memberships and settings.

What This Enables:

• Join public channels on behalf of the user
• Manage channel membership for message delivery
• Ensure the integration can access channels for posting messages

What This Does Not Enable:

• Create or delete channels
• Modify channel topics or purposes without user action
• Access private channels

chat:write

Description: Send messages on a user's behalf.

What This Enables:

• Post record card notifications to Slack channels
• Send direct messages to individual Slack users
• Deliver formatted messages with headings, fields, and action buttons
• Execute Slack Message automation tasks

What This Does Not Enable:

• Read or modify existing messages
• Delete messages posted by others
• Access message history

groups:read

Description: View basic information about a user's private channels.

What This Enables:

• List private channels the authorizing user belongs to
• Retrieve private channel names and IDs for automation configuration
• Display private channel options in Slack Message task dropdowns
• Identify available private channels for targeted notifications

What This Does Not Enable:

• Read message content or history in private channels
• Access private channels the user is not a member of
• Add or remove members from private channels

im:read

Description: View basic information about a user's direct messages.

What This Enables:

• List direct message conversations the user has
• Identify users available for direct message delivery
• Retrieve direct message channel IDs for automation configuration

What This Does Not Enable:

• Read the content of direct messages
• Access direct message history
• View direct messages between other users

mpim:read

Description: View basic information about a user's group direct messages.

What This Enables:

• List group direct message conversations the user participates in
• Identify group direct message channels for potential message delivery
• Retrieve group direct message channel IDs

What This Does Not Enable:

• Read the content of group direct messages
• Access group direct message history
• View group direct messages the user is not part of

users:read

Description: View people in a workspace.

What This Enables:

• List users in the Slack workspace
• Retrieve user display names and IDs for automation configuration
• Display user options in Slack Message task dropdowns for direct messages
• Identify valid recipients for direct message notifications
• Look up user information for message delivery

What This Does Not Enable:

• Access user email addresses (requires users:read.email)
• Modify user profiles or settings
• View user activity or presence status

users:read.email

Description: View email addresses of people in a workspace.

What This Enables:

• Retrieve email addresses associated with Slack users
• Match Slack users to Magentrix users by email address
• Support user identification across systems
• Enable email-based user lookup for automation targeting

What This Does Not Enable:

• Send emails to users
• Modify user email addresses
• Access other personal information beyond email

Bot Token Scopes

Bot token scopes enable the Magentrix bot to perform actions as the application itself. Bot actions appear as coming from the app rather than an individual user.

users:read

Description: View people in a workspace.

What This Enables:

• List users in the Slack workspace via bot API calls
• Retrieve user information for bot-initiated operations
• Look up user details when processing automation tasks
• Identify workspace members for notification targeting

What This Does Not Enable:

• Access user email addresses via bot token
• Modify user profiles
• View private user information

users:write

Description: Set presence for the bot user.

What This Enables:

• Set the bot's presence status (online, away)
• Maintain bot availability indicators in Slack
• Support the "Always Show My Bot as Online" functionality

What This Does Not Enable:

• Modify other users' presence or profiles
• Change workspace-wide settings
• Access user account settings

Scope Summary Table

The following table summarizes all scopes used by Magentrix Slack Integration:

What Magentrix Cannot Do

Understanding what the granted scopes do not permit helps address security and privacy concerns. Magentrix Slack Integration cannot:

Message Content and History

• Read the content of any messages in channels or direct messages
• Access message history or archives
• Search through existing conversations
• View reactions, threads, or replies on messages
• Edit or delete messages posted by users

Workspace Administration

• Create, rename, or delete channels
• Modify workspace settings or policies
• Add or remove users from the workspace
• Change user roles or permissions
• Access workspace billing or administrative information

User Privacy

• View user activity, status messages, or presence beyond basic online indicators
• Access user profile details beyond name and email
• Monitor user behavior or usage patterns
• View direct messages between other users
• Access files shared in conversations

External Communications

• Send messages to external Slack workspaces
• Access Slack Connect channels with external organizations
• Interact with external users or guests beyond the authorized workspace

Security Considerations

Principle of Least Privilege

The Magentrix Slack Integration requests only the scopes necessary to deliver automated notifications. The scope set is designed to enable message delivery while minimizing access to sensitive information. No scopes are requested for reading message content, accessing files, or performing administrative actions.

Channel Visibility

The channels:read and groups:read scopes allow Magentrix to list channels for configuration purposes, but do not grant access to channel content. Administrators selecting target channels in automation tasks see channel names but not channel conversations.

User Information Access

The users:read and users:read.email scopes enable user lookup for direct message targeting and user matching. This information is used solely for automation configuration and message delivery, not for monitoring or profiling users.

Token Security

OAuth tokens issued during workspace authorization are stored securely within Magentrix. Tokens can be revoked at any time through the Connected Workspaces management interface or through Slack workspace settings. Revoking a token immediately terminates Magentrix's access to that workspace.

Compliance and Audit Information

Data Access Summary

For compliance documentation, Magentrix Slack Integration accesses the following data categories:

• Channel Metadata: Channel names, IDs, and membership information (not message content)
• User Directory: User names, IDs, and email addresses for workspace members
• Conversation Metadata: Direct message and group message channel identifiers (not message content)

Data Transmission

Magentrix transmits the following data to Slack:

• Record Card Messages: Formatted notifications containing record field labels and values as configured in automation tasks
• Message Metadata: Target channel or user identifiers, message formatting instructions

Data Storage

Magentrix stores the following Slack-related data:

• OAuth Tokens: Access tokens for authorized workspace connections
• Connection Metadata: Workspace IDs, user IDs, connection dates, and ownership information
• Configuration Data: Automation task settings including target channels, users, and field selections

Magentrix does not store Slack message content, channel conversations, or user activity data.

Custom Slack App Scope Modifications

Organizations using Custom Slack Apps can modify the requested scopes based on their specific requirements. However, removing required scopes will disable corresponding functionality.

Required Scopes

The following scopes are required for basic Slack Integration functionality:

• chat:write (User): Required for sending any messages to Slack
• users:read (User): Required for user lookup and direct message targeting

Optional Scopes

The following scopes can be removed if corresponding functionality is not needed:

• channels:read: Remove if only using direct messages (disables channel selection)
• channels:write: Remove if bot will be manually invited to all target channels
• groups:read: Remove if not targeting private channels
• im:read: Remove if not using direct message features
• mpim:read: Remove if not targeting group direct messages
• users:read.email: Remove if email-based user matching is not needed
• users:write (Bot): Remove if bot presence status is not important

Slack API Documentation References

For additional technical details about Slack permission scopes, consult Slack's official documentation:

• Scopes and Permissions:https://api.slack.com/scopes
• OAuth Documentation:https://api.slack.com/authentication/oauth-v2
• Bot Token Scopes:https://api.slack.com/authentication/token-types

Slack's documentation provides comprehensive technical specifications for each scope, including API methods enabled by each permission and detailed security considerations.

Understanding Slack permission scopes ensures administrators can confidently authorize workspace connections, address security questions, and configure Custom Slack Apps appropriately for their organizational requirements.

Jump to Slack Integration Checklist

<< Creating a Custom Slack App | Slack Integration Best Practices >>