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.
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:
When a linked IDP group is removed from a channel’s membership list:
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:
admin.*
scope you want. Click the green Save Changes
button.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.
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)
Argument | Type | Description |
---|---|---|
token |
string | Your API access token, imbued with the admin.conversations:write scope. |
team_id |
string | The workspace where the channel exists. |
group_id |
string | The org-level IDP group you wish to link to a channel. |
channel_id |
string | The channel you wish to link to. |
{
"ok": true
}
Error | Description |
---|---|
team_not_found |
Returned when team_id can’t be resolved. |
group_not_found |
Returned when group_id can’t be resolved. |
channel_not_found |
Returned when channel_id can’t be resolved. |
invalid_channel |
Returned when channel can’t be linked to an IDP group (i.e. a public channel or external shared channel). |
not_an_admin |
Returned when token is associated with a user who is not an org admin or owner. |
invalid_auth |
Returned if the provided team_id is not an Enterprise team. |
default_channel_restricted |
Returned if the provided channel_id is a default channel for the workspace. |
unable_to_link_idp_group_and_channel |
Returned if we fail to link the group to the channel. |
channel_is_not_private |
Returned when the channel is not private. |
group_must_not_be_empty |
Returned when the group has no members. |
limit_reached |
Returned when the group or the channel is at the maximum number of connections. |
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)
Argument | Type | Description |
---|---|---|
token |
string | Your API access token, imbued with the admin.conversations:write scope. |
team_id |
string | The workspace where the channel exists. |
group_id |
string | The org-level IDP group you wish to unlink from a channel. |
channel_id |
string | The channel you wish to unlink from. |
{
"ok": true
}
Error | Description |
---|---|
team_not_found |
Returned when team_id can’t be resolved. |
group_not_found |
Returned when group_id can’t be resolved. |
channel_not_found |
Returned when channel_id can’t be resolved. |
invalid_channel |
Returned when channel can’t be linked to an IDP group (ie a public channel or external shared channel). |
not_an_admin |
Returned when token is associated with a user who is not an org admin or owner. |
invalid_auth |
Returned if the provided team_id is not an Enterprise team. |
failed_to_unlink_channel |
Returned when we fail to unlink the group from the channel. |
link_not_found |
Returned when we cannot locate a link between the channel and group ID. |
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)
Argument | Type | Description |
---|---|---|
token |
string | Your API access token, imbued with the admin.conversations:read scope. |
team_id |
string | The workspace where the channel exists. |
channel_id |
string | The channel you wish to see linked groups for. |
{
"ok": true,
"group_ids": [
"XYZ",
"ABC"
]
}
Error | Description |
---|---|
team_not_found |
Returned when team_id can’t be resolved. |
channel_not_found |
Returned when channel_id can’t be resolved. |
invalid_channel |
Returned when channel can’t be linked to an IDP group (ie a public channel or external shared channel). |
not_an_admin |
Returned when token is associated with a user who is not an org admin or owner. |
invalid_auth |
Returned if the provided team_id is not an Enterprise team. |