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
- Creating a workspace
- Managing users in a workspace
- Looking up workspace owners, admins, and users
- Setting allowlists for private channels
- Parting thoughts
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.
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:
admin.conversations.restrictAccess.addGroup
admin.conversations.restrictAccess.removeGroup
admin.conversations.restrictAccess.listGroups
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.