Using APIs with organization-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 organization-wide app. That's because your organization-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 organization-wide installation.
  • There are a few new events and methods to help you keep track of which workspaces within an organization-wide deployment your app actually has access to.

Read on for more detail on each of the above changes to calling APIs with your organization-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. You may have certain installations of your app that are on a single workspace, while other installations are deployed across entire organizations. In this case, a 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.

The team_id is only relevant when using an org-level token. This field will be ignored if the API call is sent using a workspace-level token.

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

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 organization-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 organization-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 organization-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 organization you've got access to.