Go to Slack
Documentation Tutorials Twitter
HomeApps for AdminsApps for Slack Admins

Managing users in Enterprise Grid workspaces

The perfect workspace is like the perfect cup of coffee: a carefully-crafted container, filled to the brim with stimulating stuff.

Like a great cup of coffee, a workspace takes some time to craft: creating it, populating it with the right users, and setting admins and owners.

As the espresso machine revolutionized coffee, so too is there an express-track, programmatic way to construct workspaces: the APIs for managing users in a workspace.

All of the fine-tuned crafting of a perfect workspace, with none of the wasted time for admins. In an Enterprise Grid organization, your app can create a new workspace and get it running with the right users and admins, all in the time it takes a barista to pull a perfect shot of espresso.

Read on to learn how.

Getting started

You'll need three scopes to allow your app to create workspaces and manage users:

  • admin.teams:write allows your app to create a workspace.
  • admin.teams:read allows your app to list owners or admins for a worksapce.
  • admin.users:write allows your app to assign, invite, and remove users in a workspace. It also allows your app to designate a user as an admin, owner, or regular user.

All admin.* scopes are obtained using the normal OAuth flow, but there are a few extra requirements. The OAuth installation must be initiated by an Enterprise Grid admin or owner. Also, the install must take place on the Enterprise Grid org, not on an individual workspace using the workspace switcher during the install flow.

Installing the app on a workspace

Check out the scope documentation for more detail.

Creating a workspace

Craft your workspace at espresso speed with the admin.teams.create method:

curl -F token=xoxp-... -F team_domain='slacksoftballteam' -F team_name='Slack Softball Team' https://slack.com/api/admin.teams.create

Managing users in a workspace

A workspace starts out as a pristine porcelain container, empty and clean. But the real fun starts with conversation, and conversations need users.

Start off by inviting and assigning new or existing Grid users, respectively, into a workspace.

Inviting a user

Inviting a user is a polite first move. You'll invite users via email, just like you would using the Slack user invitation UI. The user doesn't have to be a member of your Grid organization yet.

Use the admin.users.invite method to invite a new user. You can specify channels that you'd like the user to join using the channel_ids parameter:

curl -F token=xoxp-... -F team_id=T1234 -F channel_ids=C1234 email=nomar@slack.com https://slack.com/api/admin.users.invite

You also have the option to designate the user as a single-channel or multi-channel guest by using the is_restricted and is_ultra_restricted parameters respectively.

Assigning a user

Assign an existing Enterprise Grid user to a workspace if you want to skip the polite dance of invitation. If the user has previously been removed or left the workspace, they'll still be reinstated as a member.

Use the admin.users.assign method to assign a user to a workspace:

curl -F token=xoxp-... -F team_id=T1234 -F user_id=U1234 https://slack.com/api/admin.users.assign

Again, you have the option to designate the user as a single-channel or multi-channel guest by using the is_restricted and is_ultra_restricted parameters respectively.

Removing a user

All good things must come to an end, even membership in the most memorable workspace. To remove a user, use the admin.users.remove method:

curl -F token=xoxp-... -F team_id=T1234 -F user_id=U1234 https://slack.com/api/admin.users.remove

Designating a user as an admin, owner, or regular user

You can fine-tune the flavor of your workspace by promoting a user to an admin or workspace owner role. You can even upgrade a guest to a full user.

Here's the admin.users.setAdmin method:

curl -F token=xoxp-... -F team_id=T1234 -F user_id=U1234 https://slack.com/api/admin.users.setAdmin

And the corresponding admin.users.setOwner method:

curl -F token=xoxp-... -F team_id=T1234 -F user_id=U1234 https://slack.com/api/admin.users.setOwner

And, if you'd like to designate someone as a regular old user, you can do that too with the admin.users.setRegular method.

curl -F token=xoxp-... -F team_id=T1234 -F user_id=U1234 https://slack.com/api/admin.users.setRegular

Fun fact: all three of these methods can be used either as promotion or demotion. So, for example, you can use the setRegular method to promote a single-channel guest into a full user, or you can use the same method to demote an admin into a regular user.

Looking up workspace owners or admins

Your app can grab a list of workspace owners using the admin.teams.owners.list method:

curl -F token=xoxp-... -F team_id=T1234 -F https://slack.com/api/admin.teams.owners.list

You can also use the corresponding method for admins:

curl -F token=xoxp-... -F team_id=T1234 -F https://slack.com/api/admin.teams.admins.list

Finally, you can list users with the admin.users.list method:

curl -F token=xoxp-... -F team_id=T1234 -F https://slack.com/api/admin.users.list

Setting allowlists for private channels

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.

The Private Channel Management APIs allow you to create a membership “allowlist” for both private, single-workspace channels and private cross-workspace shared channels.

Note: These APIs may not be used for public channels or channels that are shared externally to different Grid organizations.

To add, remove, or list current private channel allowlists, use the following methods:

For more details on the individual methods, check out the documentation above.

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

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

  • 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 allowlist:

  • Members will be removed from the channel unless they remain on the channel allowlist 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.

Parting thoughts

Much like the beloved pour-over coffee, manually creating a workspace still makes for some great results. However, sometimes an Enterprise Grid org admin doesn't have time to make hundreds of cups of coffee, or hundreds of workspaces.

When time is pressing and the number of workspaces mounts, the APIs for creating workspaces and managing users can help. Looking for still more APIs to soothe the wounded souls of admins? Check out other APIs for help in administering and managing workspaces.

Audience
Expert
Read first