Advanced

Managing app approvals in Enterprise Grid workspaces

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.

Sure, it might sound like a meta-machine best left to science fiction—but an app to approve other apps can make admins' lives far more pleasant and productive.

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.

To build an app with the APIs for app management, read on.

Overview
Setup with scopes
Listen with the app_requested event
Manage with approve and restrict methods

This API can only be used by Enterprise Grid orgs.

Overview

When an admin turns on the Approve apps setting in Slack, apps are requested by a Slack user and have to be approved by an admin before they're actually installed for a team to use.

The approval process helps admins make sure that each app installed on a workspace is trustworthy.

However, for Enterprise Grid admins handling approvals, app requests for each individual workspace in the org 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.

Now, app approval can be managed by a single app, across all workspaces. Instead of using the UI, Enterprise Grid admins delegate the approval work to an app. The app can implement any specific logic that the admin would like—for example, whitelisting 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.

This API can only be used by Enterprise Grid orgs.

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

Setup with scopes

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

The admin.apps:read scope allows the app to list app install requests, and to subscribe to the app_requested event.
The admin.apps:write scope allows the app to approve or restrict requests for an app install.

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 scope documentation for more detail.

Listen with the `app_requested` event

Now that you've got your management app off the ground, 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 org requests that an app be installed.

Subscribe to the app_requested event by navigating to your App page and clicking on Event Subscriptions in the left 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 containing info on 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 gives info about whether the app was approved or restricted previously.
user gives info on the user that requested the install.
team gives info about the team that the user requested the install on.
scopes gives info about 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 app directory.
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, of course, 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, restrict (in other words, deny) 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 an example app that uses these methods, look no further than this app built by Slack on Github.

Parting words

App approvals build confidence that a Slack org is safe and secure. However, managing apps for every workspace in a Grid org 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. Stay tuned for more announcements as Slack continues its quest to make admin lives even more pleasant and productive.