Comparing the Slack Discovery API With the Web API

Slack includes multiple APIs to access different types of content within various editions of Slack. For example, in addition to the general workspace-based Web API, Slack also has a separate set of Discovery and Audit APIs to work with Slack Enterprise. In this article, we’ll explore some of the differences in the capabilities of these two APIs.

Apps connecting to Slack’s Discovery API encounter some key differences from the Web API. The clearest one is the scope of accessible resources. A workspace app uses an access token to access resources such as channels, messages, files, and users in a single workspace. If that user or bot connects to multiple workspaces, the app requires a separate access token to access data in each of those workspaces.

On the other hand, a Slack Enterprise app can access all resources in multiple workspaces within that Enterprise account using a single access token, as well as resources shared among those workspaces. Slack achieves this with an extra layer above workspaces called "Enterprise Grid" that the workspaces are grouped within. Resources such as channels can be shared across workspaces in the grid.

The permissions available vary between the two types of apps. Workspace apps can request a wide range of granular permissions, which can be combined to achieve an app’s desired level of access. For example, the scopesusers:read, users:read.email, channels:read, and more. An Enterprise app only has two permission levels available — discovery:read, and discovery:write. Slack’s Discovery API guide suggests requesting only discovery:read for eDiscovery use cases, while including discovery:write if the app requires DLP functionality.

The Discovery API’s methods are similar to the Web API’s but include a subset of the available actions with a broader range of access. Below is a table that highlights these differences.

Above, “channels” refers to all channel-like object types, including public channels, private channels, direct messages, and multi-party direct messages.

The comparison above demonstrates that the Discovery API aims to provide sufficient access to scan and retrieve all message and file content in the Enterprise Grid account and remove them if needed to remediate any threats or policy violations. However, it doesn’t provide access to create new channels, messages, or files.