Advanced

Using APIs with org-wide apps

For the most part, APIs at Slack work the same with all apps—whether with an app that's deployed to an entire Enterprise organization or a single-workspace app.

There are three things to keep in mind:

  • Some API methods require a team_id when called by an org-wide app. That's because your org-wide app has access to many workspaces, and you now need to specify which workspace a method should act on.
  • Event payloads now contain info on the authorizations that they apply to, with a special is_enterprise_install boolean field to indicate that the event is being sent to an org-wide installation.
  • There are a few new events and methods to help you keep track of which workspaces within an org-wide deployment your app actually has access to.

Read on for more detail on each of the above changes to calling APIs with your org-wide app.

API methods that accept team_id

Since your app's token now can represent installations in many workspaces, some API methods will require a team_id to indicate which workspace to act on.

Here's the full list of methods that require team_id when used by an org-wide app:

You might have certain installations of your app that are on a single workspace, while other installations are deployed across entire organizations. In this case, a handy shortcut is to always pass team_id to these methods. Even if your token is a single-workspace installation, the extra parameter will be accepted.


Event payload overview

The updated Events API includes authorizations inside the event payload on most events.

authorizations tells you which installation the event applies to. You can find more detail on the updated Events API here.

Here's a sample payload:

{
    "token": "XXYYZZ",
    "is_ext_shared_channel": false,
    "team_id": "TXXXXXXXX",
    "api_app_id": "AXXXXXXXXX",
    "event": {...},
    "type": "event_callback",
    "event_id": "EvXXXXXXXX",
    "event_time": 1234567890,
    "authorizations": [
        {
            "enterprise_id": "E324567",
            "team_id": "T423567",
            "user_id": "W43567",
            "is_bot": false,
            "is_enterprise_install": true
        }
    ]
}

One note: authorizations is truncated at a single installation, so if your app is installed multiple ways and you're not sure which installs have the ability to see the event, call the apps.event.authorizations.list method to get a full list of installations.

You'll also see a relatively new field inside authorizations: that's is_enterprise_install, a boolean that tells you whether the event is being sent to an org-wide installation of your app.


New events and methods

With new power comes new abilities: apps deployed across entire orgs have access to a few new events and methods.

Two events indicate to you when your org-wide app has gained or lost access to a new workspace within your org. Those are the team_access_granted and team_access_revoked methods.

Subscribe to these events as with any other part of the Events API. That way, you'll always have an up-to-date list of workspaces to monitor and act in.

In addition, there's a handy new method to obtain a full list of workspaces your org-wide app has been approved for: the auth.teams.list method. Call it with your token (from installing your app on an Enterprise org) to see all the workspaces within that org you've got access to.