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.

---

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 workspace.
• 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.

Check out the scope documentation for more detail.

---

Creating a workspace

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

---

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, and can also 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.

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.

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

You can fine-tune the flavor of your workspace by designating users as an admin, owner or regular user. The user's current designation doesn't matter; all three methods can promote and demote users. Use the corresponding method to set a user to that specific user type:

• Set a user as an admin with the admin.users.setAdmin method
• Set a user as an owner with the admin.users.setOwner method
• Set a user as a regular old user with the admin.users.setRegular method

Looking up admins, owners, and regular users

You can check which users are admins, workspace owners, and regular users by making use of three API methods, one for each type:

• Return the list of workspace owners with the admin.teams.owners.list method
• Return the list of admins with the admin.teams.admins.list method
• Return the list of regular users with the admin.users.list method

Designating a user's role

Adding a role assignment to a user grants them the permission scopes that are assigned to that role. You can control role assignments with three methods:

• Add a role assignment to a user with the admin.roles.addAssignments method
• remove a role assignment from a user with the admin.roles.removeAssignments method
• See all existing role assignments in your organization with the admin.roles.listAssignments method.

---

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.

• Add a private channel allowlist with the admin.conversations.restrictAccess.addGroup method
• Remove a private channel allowlist with the admin.conversations.restrictAccess.removeGroup method
• List private channel allowlists with the admin.conversations.restrictAccess.listGroups method

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. Combine with our other APIs for help in administering and managing workspaces to soothe the wounded souls of admins.