You must enable javascript in order to use the Slack API Documentation. You can do this in your browser settings.
Go to Slack

Managing team members with the SCIM API

Provision and manage user accounts and groups with the Slack SCIM API. SCIM is used by Single Sign-On (SSO) services and identity providers to manage people across a variety of tools, including Slack. It's also possible to write your own apps and scripts using the SCIM API to programatically manage the members of your workspace.

Please note that the SCIM API is only available to Slack workspaces on the Plus plan and Slack Enterprise Grid.

What can the SCIM API do?

SCIM is an API for managing the people on your team and the groups they belong to.

SCIM is an open standard supported by myriad services. It behaves slightly differently than other Slack APIs. For example, most of Slack's APIs can be described as "REST-like" but are, more accurately, actually RPC-style methods that use HTTP GET and POST interchangeably but no other verbs (such as PATCH or DELETE). SCIM, being a more proper REST API, expects HTTP verbs to be used in a specific manner.

While other APIs are for interacting with a Slack workspace directly, the SCIM APIs allow teams on the Plus and Enterprise Grid plans to administer the users on a workspace (or in an organization, in the case of Grid). If you've found yourself wishing for a set of users.admin.* endpoints, SCIM might be right for you.

Slack's SCIM implementation targets version 1.1 of the protocol.

Slack supports member provisioning via helper apps with supported identity providers. This document covers custom SCIM operations.

Be aware that it's possible to deprovision an entire workspace or Enterpise Grid org with SCIM. Please test your scripts thoroughly before executing them. Of course, our support team is ready to assist you should you run into any trouble.

How do I call the SCIM API?

Before using the SCIM API, you must generate an API token via the Test Token Generator. At this time, only tokens generated by the Test Token Generator will work with the SCIM APIs and they must be generated by an admin on the team workspace or Grid org. The API token must be included via an Authorization header with a type of Bearer.

The base URL for all calls to the SCIM API is https://api.slack.com/scim/v1/. All SCIM methods are branches of this base URL.

Being a REST API, the HTTP verb (e.g. GET or POST or PATCH or even DELETE) used for each API method is important. Typically you will use GET to retrieve information, POST to create new objects, PUT and PATCH to modify objects, and DELETE to remove.

Provide a JSON request body for POST, PUT, and PATCH write operations, and set your HTTP Content-type header to application/json.

An example SCIM call might look like this:

    GET /scim/v1/Users HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

SCIM API endpoints

The SCIM API is RESTful and the endpoint URLs are different than other Slack API endpoints.

Service Provider Configuration

GET /ServiceProviderConfigs Returns Slack's configuration details for our SCIM API, including which operations are supported.

Schemas

Slack currently supports schemas for users and groups. Querying the schemas will provide the most up-to-date rendering of the supported SCIM attributes.

GET /Schemas/Users Returns Slack's configuration details for how users are formatted.

GET /Schemas/Groups Returns Slack's configuration details for how groups are formatted.

Users

As you might expect, users map to the individuals of your team across a workspace or Grid organization. Each user contains properties called attributes, like userName and title. You can list users, filter by attribute, add new users, update a user's profile information, or remove a user entirely.

User attributes

Attributes are the details associated with a user's account. These are the details that someone would typically set in their profile (for example, by clicking the Edit Profile button in the Slack application).

The following tables map SCIM attributes to the profile fields that Slack uses. Most of these profile fields are exposed directly in a person's profile in the Slack UI. Sometimes, mulitple SCIM attributes map to a single Slack profile field — for example, Slack's Display name field will populate from either the displayName or the userName SCIM attribute, depending on which is set. If both are set, it will use displayName.

Attribute values will vary by identity provider. For example, some may use a single field for a user's full name, others may provide sub-attributes such as givenName and familyName, still others may provide both. Either is acceptable, but they should only describe the same name (i.e. sub-attributes should not contain additional or optional information, such as a nickname).

Not every attribute will be displayed in a user's profile — for example, active does not appear as a field but can be used to determine if a user's account is active.

The password attribute is never returned but can be used to set the initial password for a user if the team is not using an identity manager.

Slack Profile Field SCIM Attribute Attribute Type Required
Username userName Singular True
Full Name name, { givenName, familyName } Singular False
Nickname nickName Singular False
Display Name displayName, userName Singular False
Email emails[0]['value'] Multi-Valued True
Profile URL profileUrl Singular False
Profile Photo photos[0]['values'] Multi-Valued False
Groups groups Multi-Valued False
What I Do title Singular False
Timezone timezone Singular False
Active active Singular False
Password password Singular False

Slack will also create profile fields if the following SCIM attributes are present:

Custom Profile Field SCIM Attribute Attribute Type
Addresses addresses Multi-Valued
Roles roles Multi-Valued
Phone phoneNumbers[0]['values'] Multi-Valued
UserType userType Singular
Cost Center enterprise.costCenter Singular
Country addresses[primary]['country'] Singular
Department enterprise.department Singular
Division enterprise.division Singular
Employee ID enterprise.employeeNumber Singular
Honorific Prefix name.honorificPrefix Singular
Locale locale Singular
City addresses[primary]['locality'] Singular
Manager enterprise.manager.managerId Singular
Organization enterprise.organization Singular
Zip Code addresses[primary][‘postalCode’] Singular
Preferred Language preferredLanguage Singular

User methods

GET /Users Returns a paginated list of users, ten users per page by default. Use the startIndex and count query parameters to paginate long lists of users.

It's possible to return a list of specific types of users with the filter parameter.

    GET /scim/v1/Users?startIndex=4&count=500 HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

GET /Users/{id} Retrieves a single user resource. The value of the {id} should be the user's corresponding Slack ID, beginning with either U or W.

    GET /scim/v1/Users/U1A23BC4D HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

POST /Users Creates a user. Must include the userName attribute and at least one email address. You may provide an email address in the userName field, but it will be automatically converted to a Slack-appropriate username.

This example request body provides a detailed example of which attributes Slack uses, especially for the multi-valued attributes.

{
    "schemas": ["urn:scim:schemas:core:1.0",
              "urn:scim:schemas:extension:enterprise:1.0"],
    "userName": "other_username",
    "nickName": "slack_username",
    "name": {
        "familyName": "Last",
        "givenName": "First",
        "honorificPrefix": "Ms.",
    },
    "displayName": "First Last",
    "profileUrl": "https://login.example.com/slack_username",
    "emails": [
        {
            "value": "some@email.com",
            "type": "work",
            "primary": true
        },
        {
            "value": "some_other@email.com",
            "type": "home"
        }
    ],
    "addresses": [
        {
            "streetAddress": "1060 W Addison St",
            "locality": "Chicago",
            "region": "IL",
            "postalCode": "60613",
            "country": "USA",
            "type": "work",
            "primary": true
        },
    ],
    "phoneNumbers": [
        {
            "value": "555-555-5555",
            "type": "work"
        },
        {
            "value": "555-555-4444",
            "type": "mobile"
        }
    ],
    "photos": [
        {
            "value": "https://photos.example.com/profilephoto.jpg",
            "type": "photo"
        },
    ],
    "roles": [
        {
            "value": "Tech Lead",
            "primary": "true"
        }
    ],
    "userType": "Employee",
    "title": "Tour Guide",
    "preferredLanguage":"en_US",
    "locale": "en_US",
    "timezone": "America/Chicago",
    "active":true,
    "password":"Cub$winCub$win!!",
    "urn:scim:schemas:extension:enterprise:1.0": {
        "employeeNumber": "701984",
        "costCenter": "4130",
        "organization": "Chicago Cubs",
        "division": "Wrigley Field",
        "department": "Tour Operations",
        "manager": {
            "managerId": "U0XE15NHQ",
        }
    }
}

PATCH /Users/{id} Updates an existing user resource, overwriting values for specified attributes. Attributes that are not provided will remain unchanged.

Disabled users can be re-enabled by sending active attribute equal to true. The value of the {id} should be the user's corresponding Slack ID, beginning with either U or W.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "U0XE15NH0",
    "active": true,
    "emails": [
        {
            "value": "some@new.email.com",
            "primary": true
        }
    ]
}

PUT /Users/{id}

Updates an existing user resource, overwriting all values for a user even if an attribute is empty or not provided. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider.

Deactivated users can be re-enabled by setting the active attribute to true. The value of the {id} should be the user's corresponding Slack ID, beginning with either U or W.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "U0XE15NH0",
    "active": false,
    "userName": "other_username",
    "nickName": "slack_username",
    "name": {
        "givenName": "First",
        "familyName": "Last"
    },
    "title": "Ms.",
    "emails": [
        {
            "value": "some@email.com",
            "primary": true
        }
    ],
    "photos": [
        {
            "value": "https://some.image/url",
            "type": "photo"
        }
    ]
}

DELETE /Users/{id} Sets a Slack user to deactivated and hides this user from all future requests. The value of the {id} should be the user's corresponding Slack ID, beginning with either U or W.

    DELETE /scim/v1/Users/42 HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

Groups

Groups are for organizing users in logical divisions across a workspace, such as by team or affinity.

Slack Group Field SCIM Attribute Attribute Type Required
Name displayName String True
Members members Multi-valued True

Group attributes

Attributes are the details associated with a group.

GET /Groups Returns a paginated list of groups, ten groups per page by default. Use the startIndex and count query parameters to paginate long lists of groups.

It's possible to return a list of specific types of groups, using the filter parameter.

    GET /scim/v1/Groups?startIndex=4&count=500 HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

GET /Groups/{id} Retrieves a single group resource.

    GET /scim/v1/Groups/42 HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

POST /Groups Creates a new group. Must include the displayName attribute (as defined in the schema specification). Users can be added to the group during creation by supplying the Slack user ID values in the members array attribute.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "external_id",
    "displayName": "Group Name",
    "members": [
        {
            "value": "U0W0NQFFC"
        },
        {
            "value": "U0W0C30RE"
        }
    ]
}

PATCH /Groups/{id} Updates an existing group resource, allowing individual (or groups of) users to be added or removed from the group with a single operation.

Setting the operation attribute of a member object to delete will remove members from a group; add is the default operation for PATCH. More details on editing a resource with PATCH.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "members": [
        {
            "value": "U0W0NQFFC"
        },
        {
            "value": "U0W0QCPK4",
            "operation": "delete"
        },
        {
            "value": "U0W0C30RE"
        }
    ]
}

PUT /Groups/{id} Updates an existing group resource, overwriting all values for a group even if an attribute is empty or not provided. PUT will replace all members of a group with those members provided via the members attribute. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "displayName": "New Group Name",
    "members": [
        {
            "value": "U0W0NQFFC"
        }
    ]
}

DELETE /Groups/{id} Permanently removes a group (members are not deleted, only the group).

    DELETE /scim/v1/Groups/42 HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

Filter

For methods that return a list — GET /Users and GET /Groups — it's possible to filter the list by the username, email, restricted, and ultra_restricted attributes, and return only the values matching that filter. The following rules apply:

  • The filter parameter must contain one valid boolean operator
  • Each expression must contain an attribute name followed by an attribute operator, (also supports an optional value)
  • Multiple expressions may be combined using two logical operators.
  • Expressions can be grouped together using "( )"
  • Expressions must be evaluated using standard order of operations
  • String literals must be valid JSON strings

The following is a list of valid operators:

Operator Description
eq equal
co contains
sw starts with
pr prevent value
gt greater than
ge greater than or equal
lt less than
le less than or equal
and logical And
or logical Or

Attribute name and attribute operator are case insensitive. For example, the following two expressions will evaluate to the same logical value:

filter=userName Eq "Carly"
filter=username eq "carly"

Filters may be applied to the username and email user attributes, with the addition of two membership filters:

Attribute Name SCIM Attribute Attribute Type
Multi-Channel-Guest restricted Singular
Single-Channel-Guest ultra_restricted Singular

The following would return a list of all multi-channel guests of a workspace:

    GET /scim/v1/Users?filter=restricted eq '1' HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx

SCIM provisioning limitations

  • Users can not be permanently deleted from Slack, they can only be deactivated.
  • Attempts to provision a user with a duplicate email address (even if the existing user has been previously deactivated in Slack) will fail. The existing user email address must be updated manually in Slack to free up the email to be re-provisioned.
  • When creating a new user, if anything in custom profile is invalid, all profile fields will be dropped
  • Multi-Channel and Single-Channel Guests can not be fully provisioned via SCIM. You will first need to provision them as a full user, then restrict them via the Slack admin page.
  • Group mention handles (@group) can not be set via the SCIM provisioning API.
  • For Enterprise Grid teams, creating SCIM groups will create an IDP group, which may or may not be the correct behavior depending on what you hope to accomplish.
  • For Enterprise Grid, SCIM operations currently only work at the org, not workspace, level.
  • Subteams that are automatically generated by Slack, such as Team Admins, can not be updated via the SCIM API.
  • The SCIM API is rate limited. If your requests are being limited, an HTTP: 429 error will be returned. See the rate limits page for more detail.