HomeEnterpriseOrganization-wide apps

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 org-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 org-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!

List of methods that use team_id with org-wide apps

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

Recommended reading

Related content