Reference

This page contains sample reference payloads and method calls for apps deployed across entire organizations.

Sample oauth.v2.access response

The OAuth flow for an organization-wide app uses identical endpoints to any other Slack app. One difference is that you'll need to determine whether the installer deployed your app to an entire org, rather than a single workspace. Use the is_enterprise_install boolean in the response from oauth.v2.access.

{
    "ok": true,
    "access_token": "xoxb-XXXX",
    "token_type": "bot",
    "scope": "identify,users:read",
    "bot_user_id": "W0XXXX",
    "app_id": "A0UXXXX",
    "team": null,
    "enterprise": {
        "id": "E1XXX",
        "name": "Starship"
    },
    "is_enterprise_install": true,
    "authed_user": {
        "id": "WXXXX",
        "access_token": "xoxp-XXXX"
            ...
    }
}

You'll want to consider redirecting your installer after OAuth for your organization-wide app, since the app won't actually be added to any workspaces yet. Consider redirecting to a modal that adds the app to workspaces, so that you can remind the installing Admin that they still need to do so:

https://app.slack.com/manage/{your enterprise id}/integrations/profile/{your_app_id}/workspaces/add

Sample event payload

This event payload shows the new authorizations field, containing the is_enterprise_install boolean.

{
    "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
        }
    ]
}

Remember: authorizations is truncated to one item, so call the apps.event.authorizations.list method to get a full list of installations.


Sample API call with team_id

Try out the API method tester for conversations.list, and supply a team_id to see sample cURL commands to run!

The context_team_id field

In addition to the team_id field, another you may come across in your org-wide travels is the context_team_id field.

We use this field behind the scenes to resolve which channels come from which workspaces within the organization, and what roles and preferences are applied to those channels. For all channel types, this field represents the perspective through which the viewing user is accessing the channel. Let's look at an example.

Let's say there is an Enterprise Grid instance called Middle Earth. Within that instance, there are two workspaces: Rohan and Gondor. You are a user in the Gondor workspace.

  • For both workspace's non-shared channelsβ€”or for all channels that may be shared, but are hosted by your team (in this case, Gondor)β€”the team ID comes from the team_id field.
  • Now, someone in the Rohan workspace shares the #oath-of-eorl channel with Gondor. In this case, since the shared channel is hosted by the "away" workspace, the team ID comes from the context_team_id field.

This field is used in outgoing dispatches only (such as Block Kit actions and other similar events); that is, it's not a field you'll be supplying to an API method call. We just wanted you to be aware of it and what it's used for in case it shows up in your logs! However, you can optionally supply this same information by using the client_context_team_id field when calling any API method that requires the channel argument. A couple examples are the chat.postMessage or chat.update API methods.


List of methods that use team_id with organization-wide apps

More methods might be added to this list as we discover more methods that would benefit from accepting a team_id with organization-wide apps. Right now, the list of methods is: