Private channel management

Typically, any member of a private channel can invite anyone else belonging to their workspace into the channel.

However, you may need to restrict access to private channels due to sensitive or confidential information.

These Private Channel Management APIs allow you to create a membership list for both private, single-workspace channels and private cross-workspace shared channels.

Note: These APIs can't be used for channels that aren't private or that are shared externally to different Grid organizations.

Now, any private channel (except a default channel) can have an IDP group added to the channel’s membership list. Users in the list don't automatically get added to the channel—but only users who belong to a listed group can be added to the channel.

Overview

Here's a brief overview of what to expect when you create a membership list for a private channel by linking an IDP Group:

When a linked IDP group is added to a channel's membership list:

• If the added IDP group is the first group linked to this channel, any user who is not a member of that group is removed from the channel.
• Members of the linked IDP group are not immediately added to the channel. They must be manually invited by a channel member.
• Users who are not in one of the IDP groups linked to a channel cannot be invited to the channel.
• Multiple IDP groups can be linked to a channel, but each API call must be made separately.

When a linked IDP group is removed from a channel’s membership list:

• Members will be removed from the channel unless they remain on the channel list through membership in another IDP group.
• When a user is removed from an IDP group, they will be removed from any channels linked to that IDP group (unless they have access to the channel through membership in another IDP group).
• If a channel is linked to a single group, the group must be disconnected from the channel before the group can be deleted.
• If a channel is unlinked from all groups, it becomes a regular private channel—anyone can be invited.
• If you send a SCIM request to remove over 1,000 users from a group that is linked to a channel, all in one request, the API call will fail.

Getting started

You’ll need the admin.conversations:write scope to allow your app to link or unlink groups from private channels.

This admin scope is obtained through version two of the OAuth V2 flow, but there are a few additional requirements. The app requesting this scope must be installed by an Admin or Owner of an Enterprise Grid organization. Also, the app must be installed on the entire org, not on an individual workspace. See below for more details.

If the app is installed by an Org Admin or Owner, ensure the Channel Management settings provide the appropriate permissions. In order to manage channels after they are created, you must update your token to enable permissions for Org Admins or Owners (not just the Primary Org Owner).

Admin API endpoints reach across an entire Enterprise Grid organization, not individual workspaces.

For a token to be imbued with admin scopes, it must be obtained from installing an app on the entire Grid org, not just a workspace within the organization.

To configure and install an app supporting Admin API endpoints on your Enterprise Grid organization:

1. Create a new Slack app. Your app will need to be able to handle a standard OAuth 2 flow.
2. In the app's settings, select OAuth & Permissions from the left navigation. Scroll down to the section titled Scopes and add the admin.* scope you want. Click the green Save Changes button.
3. In the app's settings, select Manage Distribution from the left navigation. Under the section titled Share Your App with Other Workspaces, make sure all four sections have the green check. Then click the green Activate Public Distribution button.
4. Under the Share Your App with Your Workspace section, copy the Sharable URL and paste it into a browser to initiate the OAuth handshake that will install the app on your organization. You must be logged in as an Admin or Owner of your Enterprise Grid organization to install the app.
5. Check the dropdown in the upper right of the installation screen to make sure you are installing the app on the organization, not an individual workspace within the organization. See the image below for a visual.
6. Once your app completes the OAuth flow, you will be granted an OAuth token that can be used for calling Admin API methods for your organization.

When installing an app to use an Admin API endpoint, be sure to install it on your Grid organization, not a workspace within the organization.

Methods

Use the add method to add an IDP group to a private channel membership list. Use the remove method to remove an IDP group from a private channel membership.

admin.conversations.restrictAccess.addGroup

Add an IDP group to the list for membership in a given channel.

Scope: admin.conversations:write

Rate Limit: T2 (20+ requests/minute)

Arguments

Sample success response

{
    "ok": true
}

Possible errors

admin.conversations.restrictAccess.removeGroup

Remove a given IDP group from the membership list in a given channel. Members of this IDP group will be removed from the channel unless they remain on the channel membership list through another IDP group.

Scope: admin.conversations:write

Rate Limit: T2 (5+ req/min)

Arguments

Sample success response

{
    "ok": true
}

Possible errors

admin.conversations.restrictAccess.listGroupsLinkedToChannel

Lists the IDP groups that form the membership list in a given channel. Only members of these IDP groups may access the channel.

Scope: admin.conversations:read

Rate Limit: T2 (20+ req/min)

Arguments

Sample success response

{
    "ok": true,
    "group_ids": [
        "XYZ",
        "ABC"
    ]
}

Possible errors