Legal Holds API

Slack's Legal Hold APIs allow developers to build applications with read and write permissions to Slack's legal holds. These applications can ensure that relevant data is saved when an organization needs to place a legal hold in Slack.

The Legal Hold APIs can do the following:

  • Create legal holds
  • Edit legal holds
  • Release legal holds

These permissions include being able to set the custodians on each legal hold, which determines the data that Slack will preserve.

Legal holds do not provide access to the contents of what is preserved. Rather, the legal hold API lets Slack know which data needs to be preserved, while the Discovery API is required to collect data.

Read on to learn how to use the Legal Holds APIs.

Setting up your Slack Workspace and Grid Org

There are a number of steps to enable usage of the Legal Holds API on a Slack Enterprise Grid.

First some prerequisites:

  • Customer must be an Enterprise customer, and app installation must happen at the top-level Enterprise org.
  • Only an Owner-level account can install the app — this should be an account created specifically for this purpose, so that the app is not tied to a single user.

And some other important info:

  • Third-party apps using the Legal Holds scopes must be approved for distribution via the App Directory before they can be installed on a customer org.
  • In Slack Connect channels (formerly externally shared channels), messages will adhere to the message poster's organization's Legal Hold policies.

Building your app

OAuth ensures a way for us to provide tokens to applications that can request data on behalf of those who install the application.

Your app's access token opens the door to Slack API methods, events, and other features. During the OAuth flow, you specify which scopes your app needs. Those scopes determine exactly which doors (methods, events, and features) your app can unlock.

Your app gains an access token in three steps:

  • Asking for scopes
  • Waiting for a user to approve your requested scopes
  • Exchanging a temporary authorization code for an access token

Scopes

Scopes at Slack are additive, but anytime a scope is added or removed, the app must be reinstalled. For the purpose of this API, please consider the following scopes based on your need.

Tokens with admin.legalHolds:* scopes are granted at the enterprise level.

Scope Purpose
admin.legalHolds:read View all of the organization’s Legal Holds policies and custodians
admin.legalHolds:write Make changes to the organization’s Legal Holds policies and custodians

OAuth tokens are associated with the user who authorizes an application. In the event that the original installer's account is deactivated or their role drops below an "Org Owner", the token will be revoked. For this reason, we encourage customers to authorize the application with an admin or persistent account to prevent disruptions.

If you have more questions about this process, you can find a more detailed description of OAuth here.

Partner app installation

Partners should create a single app that can be distributed and installed in multiple workspaces and customer instances. Customers should install the single production version of Partner applications via the App Directory (and should not create individual applications to share tokens).

On prem solutions

On prem solutions should also be condensed into a single application. An on prem customer can authenticate the app via the link in the App Directory after logging into their Slack instance. Once the OAuth handshake is completed via a link hosted within your application, the customer administrator can copy and paste the temporary code or the encrypted access token into their on prem deployment of your application. From there, requests can be made to the Legal Holds API from the on prem deployment.

For "hybrid" on-prem deployments, we also recommend adding redirect URIs for each customer instance.