Skip to main content

Managing users

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

The features within are only available to Slack workspaces on Enterprise Grid plans.

Don't have a paid plan? Join the Developer Program and provision a fully-featured sandbox for free.

A Slack app can create a new workspace populated with the right users and admins using a collection of API methods.

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.

Installing the app on a workspace

Creating a workspace​

Create your workspace with the admin.teams.create method.

Managing users in a workspace​

The real fun of a workspace starts with conversation, and conversations need users. You can invite new Grid users and assign existing Grid users to 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:

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:

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:

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 API methods allow you to create a membership “allowlist” for both private, single-workspace channels and private, cross-workspace shared channels.

These API methods may only be used for private channels, not for public channels or channels that are shared externally to different Grid organizations.

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.

Onward​

When time is pressing and the number of workspaces mounts, the API methods 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.