Go to Slack
Documentation Tutorials Twitter

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 teams on the Plus plan and Slack Enterprise Grid.

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

What can the SCIM API do?

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.

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.
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": 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 disabled 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 disabled.
  • Attempts to provision a user with a duplicate email address (even if the existing user has been previously disabled 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 details.