| The rundown | |||
|---|---|---|---|
| Read this if: | You're working with Enterprise Grid or multiple workspaces. | ||
| Read next: | Apps for enterprises | ||
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.
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.
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
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 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.
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.
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
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.
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
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.