Skip to main content

Managing app approvals

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

The features within are only available to Slack workspaces on Enterprise Grid plans.

Don't have a paid plan? Join the Developer Program and provision a fully-featured sandbox for free.

An admin app can approve or restrict other app installs across an entire Enterprise Grid org. The app handles app management for each workspace in the Grid org, replacing the UI process.

Be careful: when you install an app to manage app approvals on a Grid organization, you must process all app approvals and restrictions with this app, and the workspace-level UI App Management Settings UI options will be disabled. If you wish to restore the App Management Setting UI, you'll need to revoke the token you used to approve apps, or delete the app management app entirely.

Overview​

When an admin enables the Approve apps setting in Slack, apps must then be requested by a Slack user and approved by an admin before they're actually installed for a team to use. The approval process helps admins ensure that each app installed on a workspace is trustworthy.

However, for Enterprise Grid admins handling approvals, app requests for each individual workspace in the organization can add up to a major time-suck.

Previously, approving or restricting an app install request could only happen in a UI separate from the Slack client.

App install request in UI

Now, app approval can be managed by a single app across all workspaces. Instead of using the UI, Enterprise Grid admins can delegate the approval work to an app. The app can implement any specific logic that the admin would like—for example, allowlisting the Google Drive app on any workspace.

When you use an app to handle app management with this API, it replaces the App Management UI. The Approve apps setting is turned on for each workspace automatically.

Keep reading for a more detailed walk-through on app management.

Scopes​

Two scopes enable an app to manage app install approvals across an Enterprise Grid org: admin.apps:read and admin.apps:write.

All admin.* scopes are obtained using the normal OAuth flow, but there are a few extra requirements. The OAuth installation must be initiated by an Enterprise Grid admin or owner. Also, the install must take place on the Enterprise Grid org, not on an individual workspace using the workspace switcher during the install flow.

Installing the app on a workspace

Check out the admin.apps:read documentation for more detail.

Listen with the app_requested event​

Now that you've got your management app off the ground, you can begin listening for app install requests. The app_requested event from the Events API notifies your app of exactly those requests. It's triggered any time a user on any team in your Grid organization requests that an app be installed.

Subscribe to the app_requested event by navigating to your App page and selecting Event Subscriptions in the sidebar. The Add Workspace Event button will lead you to the app_requested event. You'll need to reinstall your app for your subscription to take effect.

Here's the truncated shape of an app_requested event:

{
  "type": "app_requested",
  "app_request":{
      'id': string,
      'app': {
        'id': string,
        'name': string,
        'description': string,
        'help_url': string,
        'privacy_policy_url': string,
        'app_homepage_url': string,
        'app_directory_url': string,
        'is_app_directory_approved': boolean,
        'is_internal': boolean,
        'developer_type': string,
        'additional_info': ?string
      },
      ...
  }
}

In addition to the app field that contains details about the app that's been requested, you'll also see some other useful fields, some of which don't always appear if they're not relevant:

  • previous_resolution: whether the app was approved or restricted previously.
  • user: the user that requested the install.
  • team: the team that the user requested the install on.
  • scopes: the scopes that the requested install will grant on your workspace.

The developer_type in each app helpfully describes its origin.

  • internal: the app was developed as part of this Enterprise Grid or workspace.
  • third_party: the app was developed by a third party, such as (but not limited to) those found in the Slack Marketplace.
  • slack: the app was built with love by Slack. Hello!

For a full payload example of an app_requested event, check out the app_requested page.

Once you've got your ear to the ground listening for app install requests, read on to learn how to respond.

Manage with approve and restrict methods​

Approve an app install request​

Approve an app request with the approve method:

curl -F token=xoxp-... -F team_id=T9876 -F request_id=1234 https://slack.com/api/admin.apps.approve

The token is required, and must be imbued with the admin.apps:write scope. Follow the instructions in the scope documentation to obtain an admin scope.

You can use either request_id or app_id to identify which app to approve. Either can be obtained directly from the app_requested event described above, or from the list method described below. The team_id is also required: it specifies which workspace the app should be approved on.

You'll receive an "ok": true response when your approval is successful.

Restrict an app install request​

Similarly, you can restrict an app install with the restrict method:

curl -F token=xoxp-... -F request_id=1234 https://slack.com/api/admin.apps.restrict

As above, the token is required, and must be imbued with the admin.apps:write scope. Follow the instructions in the scope documentation to obtain an admin scope. Either a request_id or app_id is also required to identify which app to restrict, and a team_id is required as well.

You'll receive an "ok": true response when your restriction is successful.

List app install requests​

Use the list method to see pending app install requests. The list method only shows requests that haven't yet been approved or restricted by your app.

curl -F token=xoxp-... -F team_id=T9876 https://slack.com/api/admin.apps.requests.list

You'll receive a response containing a list of app_requests, each of which is identical to what's found in the app_requested event payload described above.

Sample app​

If you're looking for a sample app that uses these methods, look no further than this admin app management app built by Slack on Github.

Workflow apps​

Workflow apps also have an admin approval process, and can have workflows added to them after approval. Those workflows would still need to respect the approved scopes discussed above. For more information about the admin approval process for workflow apps, refer to admin approval.

Parting words​

App approvals build confidence that your organization is safe and secure. However, managing apps for every workspace in a Grid organization can take time and pull focus away from the most critical tasks.

Use the APIs for app management to build an app that automates app management, and gain peace of mind without the labor-intensive manual work.