SCIM API

The Slack SCIM API is used by SSO partners to help provision and manage user accounts and groups.

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

The SCIM API is based on the open standard Simple Cloud Identity Management: Protocol 1.1.

How do I call the SCIM API?

The base URL for the SCIM API is https://api.slack.com/scim/v1/.

When calling the SCIM API, you'll need to use an API token created with our Test Token Generator. Other kinds of tokens will not work.

You must pass along the API token in the "Authorization" header, like this:

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

As a REST API, the HTTP method used for each operation is important. Typically you will use GET to retrieve information, POST to create new objects, PUT and PATCH to modify objects and collections, and DELETE for removal operations.

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

SCIM API endpoints

The SCIM API is RESTful, so the endpoint URLs are different than the Web API.

Service Provider Configuration

GET /ServiceProviderConfigs

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

Schemas

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

Which user details does Slack make use of?

Attribute Name	SCIM Attribute	Attribute Type
Username	`userName`	Singular
Name	`name`	Multi-Valued
Display name	`displayName`	Singular
Nickname	`nickName`	Singular
Profile URL	`profileUrl`	Singular
Emails	`emails`	Multi-Valued
Addresses	`addresses`	Multi-Valued
Phone numbers	`phoneNumbers`	Multi-Valued
Photos	`photos`	Multi-Valued
Roles	`roles`	Multi-Valued
UserType	`userType`	Singular
Title	`title`	Singular
Preferred language	`preferredLanguage`	Singular
Locale	`locale`	Singular
Timezone	`timezone`	Singular
Active	`active`	Singular
Password	`password`	Singular

Which Enterprise extension user details does Slack make use of?

Attribute Name	SCIM Attribute	Attribute Type
Employee Number	`employeeNumber`	Singular
Cost Center	`costCenter`	Singular
Organization	`organization`	Singular
Division	`divison`	Singular
Department	`department`	Singular
Manager	`manager`	Multi-Valued

GET /Users

Returns a list of Users in a paginated fashion. Use startIndex and count query parameters to change pagination results. Supports the filter parameter.

Filters

You can search for specific types of Users with the filter parameter. The filter parameter must meet the following conditions: * String literals must be valid JSON strings * The filter parameter must contain one valid boolean expression * 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

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 all previously listed 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

Example usage:

https://api.slack.com/scim/v1/Users?filter=restricted eq '1'        // returns all guest accounts

https://api.slack.com/scim/v1/Users?filter=ultra_restricted eq '1'  // returns all ultra restricted guest accounts

GET /Users/{id}

Retrieves a single User resource.

POST /Users

Creates a user. Must include the userName attribute (as defined in the specification) 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.

Example request body:

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": "100 Universal City Plaza",
            "locality": "Hollywood",
            "region": "CA",
            "postalCode": "91608",
            "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 Guild",
    "preferredLanguage":"en_US",
    "locale": "en_US",
    "timezone": "America/Los_Angeles",
    "active":true,
    "password":"t1meMa$heen",
    "urn:scim:schemas:extension:enterprise:1.0": {
        "employeeNumber": "701984",
        "costCenter": "4130",
        "organization": "Universal Studios",
        "division": "Theme Park",
        "department": "Tour Operations",
        "manager": {
            "managerId": "U0XE15NHQ",
        }
    }
}

PUT /Users/{id}

Updates an existing user resource, overwriting all values for a user even if an attribute is empty or not provided.

Deactivated users can be re-enabled by sending active attribute equal to true.

Example request body:

{
    "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"
        }
    ]
}

PATCH /Users/{id}

Updates an existing user resource, overwriting values for specified attributes. Attributes that are not provided will remain unchanged.
Standard PUT/PATCH operations for users. PUT means empty or not provided fields are overwritten. PATCH only updates the provided fields.
Disabled users can be re-enabled by sending active attribute equal to true.

Example request body:

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

DELETE /Users/{id}

Sets a Slack user to deactivated and hides this user from all future requests.

Groups

GET /Groups

Returns a list of Groups in a paginated fashion. Use startIndex and count query parameters to change pagination results. Supports the filter parameter.

GET /Groups/{id}

Retrieves a single Group resource.

POST /Groups

Creates a new group. Must include the displayName attribute (as defined in the specification). Users can be added to the group during creation by supplying their 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"
        }
    ]
}

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.

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

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.
The operation attribute can be used to delete members from a group, add is the default operation for PATCH.
More details.

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

DELETE /Groups/{id}

Permanently removes a group (members are not deleted, only the group)

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.
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 Slack admin page.
Group mention handles (@group) can not be set via SCIM provisioning API.
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.