Go to Slack

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.

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

What can the SCIM API do?

Which user details does Slack make use of?

  • Username - userName
  • First name - name.givenName
  • Last name - name.familyName
  • Primary email address - emails
  • Profile photo - photos
  • Title - title

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

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:

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "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"
        }
    ]
}

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.