OAuth Guide and Token Creation


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 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.

Was this page helpful?