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 programmatically 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.
Manage people in a workspace
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.
Our 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 de-provision an entire workspace or Enterprise Grid organization 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.
- Accessing the SCIM API
- Enterprise Grid
- Rate limits
- Service Provider Configuration
- Schemas
- Users
- Groups
- Filter
- Errors
- Concurrency
- SCIM Provisioning Limitations
Accessing the SCIM API
Like other Slack API's, the SCIM methods are accessed over that old standby protocol, HTTP.
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. (Alas, we seem to have lost our HEAD.)
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.
An OAuth token with the admin
scope is required to access the SCIM API. The simplest way to acquire this token is for an Org Owner to create a new Slack app, add the admin
OAuth scope, install the app, and use the generated token. If you intend to build a Slack app for other teams to install, your app will need to properly handle the OAuth flow to generate the proper token.
The API token must be included via an Authorization
header with a type of Bearer
when calling any of the SCIM methods.
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?count=1000 HTTP/1.1
Host: api.slack.com
Accept: application/json
Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx
Particulars of permissions
On Plus, only Slack Owners can generate a token to use the SCIM API. On Enterprise Grid, only Org Owners can use SCIM to modify users.
The token-generating account must remain an Owner in order to make SCIM updates.
Using SCIM on an Enterprise Grid organization
On Enterprise Grid, SCIM operations work across the entire organization, not individual workspaces. A SCIM app can provision, de-provision, and update team members in just one place rather than having to do so across every workspace in an organization.
For this reason, the OAuth token used for calling SCIM API methods must be obtained from installing the app on the organization, not just a workspace within the organization. To get a SCIM app working on a grid organization, do the following:
- The web service powering your app will need to be able to handle a standard OAuth 2 flow.
- Create a new Slack app.
- In the app's settings, select OAuth & Permissions from the left navigation. Scroll down to the section titled Scopes and add the
admin
scope and click the green Save Changes button. - In the app's settings, select Manage Distribution from the left navigation. Under the section titled Share Your App with Other Workspaces, make sure all four sections have the green check. Then click the green Activate Public Distribution button.
- Under the Share Your App with Your Workspace section, copy the Sharable URL and paste it into a browser to initiate the OAuth handshake that will install the app on your organization. You will need to be logged in as an owner of your Enterprise Grid organization to install the app.
- Check the dropdown in the upper right of the installation screen to make sure you are installing the app on the Enterprise Grid organization, not an individual workspace within the organization. (See image below.)
- Once your app completes the OAuth flow, you will be granted an OAuth token that can be used for calling all of the SCIM API methods for your organization. This token is the one your app should use to call the SCIM methods.
When installing the SCIM app, be sure to install it on your Grid organization, not a workspace within the organization.
Usergroups on Enterprise Grid work a bit differently as well. Creating SCIM groups will create an IDP group, which may or may not be the correct behavior depending on what you hope to accomplish.
Rate limits
Slack uses rate limits for the SCIM API to help provide a predictably pleasant experience.
Although the exact limits for each endpoint, listed below, are different from other Slack API methods, rate limiting for SCIM still uses the same principles as our other APIs. Please note: unlike many of the other Slack API rate limits, the limits below apply to all SCIM apps in an org, not on a per-app basis.
Small bursts above the limit are acceptable. If you receive a an HTTP 429
response from Slack, you've come up against the rate limit—parse the Retry-After
header and retry your request after that time.
Organization-wide rate limits
In your organization, Slack applies per-minute rate limits across all SCIM endpoints in certain sets.
In other words, each call to any of the endpoints in that set counts toward the same rate limit. If an org-wide rate limit is exceeded, an HTTP 429
status code is returned.
Here are the limits you'll encounter that apply throughout your entire organization:
Endpoint set | Limit (requests per minute) | Bursts (requests) |
---|---|---|
Writes: POST, PUT, PATCH, DELETE |
600 | 180 |
Reads: GET |
1000 | 1000 |
Rate limits for Users endpoints
In addition to the above org-wide limits across sets of endpoints, Slack also applies rate limits on individidual endpoints. Here are the rate limits for the Users
endpoints:
Endpoint | Limit (requests per minute) | Bursts (requests) |
---|---|---|
Get a user: GET /scim/v1/Users/{id} |
300 | 300 |
Create a user: POST /scim/v1/Users |
180 | 20 |
Update a user: PUT or PATCH /scim/v1/Users/{id} |
180 | 20 |
Delete a user: DELETE /scim/v1/Users/{id} |
180 | 20 |
Rate limits for Groups endpoints
Here are the rate limits for the Groups
endpoints:
Endpoint | Limit (requests per minute) | Bursts (requests) |
---|---|---|
Get a group: GET /scim/v1/Groups/{id} |
300 | 300 |
Create a group: POST /scim/v1/Groups |
180 | 20 |
Update a group: PUT or PATCH /scim/v1/Groups/{id} |
180 | 80 |
Delete a group: DELETE /scim/v1/Groups/{id} |
180 | 20 |
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.
Returns Slack's configuration details for how users are formatted.
Multi-Channel Guest User Schema
Slack also supports a custom extension, called urn:scim:schemas:extension:slack:guest:1.0
, that can be used to designate a user as a multi-channel guest. The details of this schema are also returned as part of the GET /scim/v1/Schemas/Users
payload. The use of this extension is currently available to Enterprise Grid customers on a limited basis.
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, multiple 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
.
Note: when you sync some user attributes to Slack via SCIM, these fields become locked in Slack and you can no longer delete them or edit them. However, you may choose to hide them from user profiles.
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 |
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 |
Title | title |
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. When querying larger Slack instances, reduce the count
parameter to 1,000 or less, and use the startIndex
parameter to paginate through users. Pagination will be required for large lists of users as of August 30, 2019.
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. The value
sub-attribute for photos
can either be a publicly accessible URL e.g. "https://photos.example.com/profilephoto.jpg"
, or a Data URL containing raw image data, e.g. "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
.
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",
"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"
}
}
}
Updates an existing user resource, overwriting values for specified attributes. Attributes that are not provided in the request will remain unchanged. The value of the {id}
should be the user's corresponding Slack ID, beginning with either U
or W
.
password
, externalId
, and profileUrl
attributes are not supported.
Deactivate activated users by setting the active
attribute equal to false
. Alternatively, re-enable deactivated users by setting the active
attribute equal to true
.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"active": true
}
Updates to the userName
attribute will also update the nickName
attribute and vice versa.
userName
attribute "cannot" be empty.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"userName": "other_username"
}
Updates to the nickName
attribute will also update the userName
attribute and vice versa.
nickName
attribute "cannot" be empty.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"nickName": "slack_username"
}
Updates a user's Slack display name profile field. The following request will update the user's handle to @First Last.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "First Last"
}
Updates a user's "What I Do" profile field.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"title": "Tour Guide"
}
Updates a user's userType
profile field.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"userType": "Employee"
}
Updates the user's preferred language profile field.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"preferredLanguage":"en_US"
}
Updates the user's locale profile field.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"locale": "en_US"
}
Updates the user's timezone profile field.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"timezone": "America/Chicago"
}
Only two user emails are stored; the primary and secondary email. The primary email may be specified by setting the primary
sub-attribute to true
. If the primary
sub-attribute is omitted, the type
sub-attribute may be specified and set to "work"
. Otherwise, if both the primary
and type
sub-attributes are omitted, the primary and secondary emails will be selected in the order they appear.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"emails": [
{
"value": "some@email.com",
"type": "work",
"primary": true
},
{
"value": "some_other@email.com",
"type": "home"
}
]
}
A user's primary email cannot be deleted, only updates are supported. Attempts to delete the primary email without providing a replacement value will result in a missing_primary_email
error. However, the secondary email may be modified at will. For example, the following request will remove the secondary email.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"emails": [
{
"value": "some_other@email.com",
"operation": "delete"
}
]
}
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"emails"
]
}
}
Only two user phone numbers are stored; the primary and secondary phone numbers. The primary phone number may be specified by setting the primary
sub-attribute to true
. If the primary
sub-attribute is omitted, the type
sub-attribute may be specified and set to "mobile"
. If both the primary
and type
sub-attributes are omitted, the secondary phone number will be updated.
type
sub-attribute means different things depending on whether it's in the request or in the response. In the request, the "type": "mobile"
sub-attribute specifies the primary phone number. In the response, "type": "mobile"
is assigned to the secondary number.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"phoneNumbers": [
{
"value": "555-555-5555",
"type": "work"
},
{
"value": "555-555-4444",
"type": "mobile"
}
]
}
The primary or secondary phone numbers may be deleted by specifying their respective values and setting the operation
sub-attribute to "delete"
. The following requests are equivalent, they will delete all of the user's phone numbers.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"phoneNumbers": [
{
"value": "555-555-5555",
"operation": "delete"
},
{
"value": "555-555-4444",
"operation": "delete"
}
]
}
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"phoneNumbers"
]
}
}
Only one user photo is stored and used as the user's profile photo. The photo may be specified by setting the primary
sub-attribute to true
. If the primary
sub-attribute is omitted, the first element in the photos
array will be selected. The value
sub-attribute for photos
can either be a publicly accessible URL e.g. "https://photos.example.com/profilephoto.jpg"
, or a Data URL containing raw image data, e.g. "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"photos": [
{
"value": "https://photos.example.com/profilephoto.jpg",
"primary": true
}
]
}
Only one user address is stored. The address may be specified by setting the primary
sub-attribute to true
. If the primary
sub-attribute is omitted, the first element in the addresses
array will be selected. Only the streetAddress
, locality
, region
, postalCode
and country
sub-attributes are supported.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"addresses": [
{
"streetAddress": "1060 W Addison St",
"locality": "Chicago",
"region": "IL",
"postalCode": "60613",
"country": "USA",
"primary": true
}
]
}
To remove a user address, provide the operation
sub-attribute set to "delete"
. An address is only deleted if the streetAddress
, locality
, region
, postalCode
and country
sub-attribute values all match the current value.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"addresses": [
{
"streetAddress": "1060 W Addison St",
"locality": "Chicago",
"region": "IL",
"postalCode": "60613",
"country": "USA",
"operation": "delete"
}
]
}
Only one user role is stored. The SCIM spec does not specify a canonical type for the roles
attribute so both of the following variations are accepted. The role may be specified by setting the primary
sub-attribute to true
. If the primary
sub-attribute is omitted, the first element in the roles
array will be selected.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"roles": [
{
"value": "Tech Lead",
"primary": true
}
]
}
or
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"roles": [
"Tech Lead"
]
}
To remove a user's role, provide the operation
sub-attribute and set it to "delete"
.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"roles": [
{
"value": "Tech Lead",
"operation": "delete"
}
]
}
Updates the user's name profile fields. Only the familyName
, givenName
and honorificPrefix
sub-attributes are supported. To update all of the name sub-attributes in one request, use the following request:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"name": {
"familyName": "Last",
"givenName": "First",
"honorificPrefix": "Ms."
}
}
Otherwise, specify only the sub-attributes to update.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"name": {
"givenName": "First"
}
}
To remove a specific name
sub-attribute, use:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"name.honorificPrefix"
]
}
}
To remove all of the name
sub-attributes, use:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"name"
]
}
}
urn:scim:schemas:extension:enterprises:1.0
Updates a user's enterprise profile fields.
manager
sub-attribute is specified, the managerId
sub-attribute "must" be specified. The value for the managerId
su- attribute must be a valid Slack ID, beginning with either U
or W
.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"urn:scim:schemas:extension:enterprise:1.0": {
"employeeNumber": "701984",
"costCenter": "4130",
"organization": "Chicago Cubs",
"division": "Wrigley Field",
"department": "Tour Operations",
"manager": {
"managerId": "U0XE15NHQ"
}
}
}
Otherwise, specify only the sub-attributes to update.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"urn:scim:schemas:extension:enterprise:1.0": {
"manager": {
"managerId": "U0XE15NHQ"
}
}
}
To remove a specific urn:scim:schemas:extension:enterprise:1.0
sub-attribute, use:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"urn:scim:schemas:extension:enterprise:1.0.manager.managerId"
]
}
}
To remove all of the urn:scim:schemas:extension:enterprise:1.0
sub-attributes, use:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"urn:scim:schemas:extension:enterprise:1.0"
]
}
}
urn:scim:schemas:extension:slack:guest:1.0
To convert a full member to a multi-channel guest with an expiration date, use:
{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:slack:guest:1.0"
],
"urn:scim:schemas:extension:slack:guest:1.0": {
"type": "multi",
"expiration": "2020-11-30T23:59:59Z"
}
}
To convert a full member to a multi-channel guest without an expiration date, use:
{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:slack:guest:1.0"
],
"urn:scim:schemas:extension:slack:guest:1.0": {
"type": "multi"
}
}
To remove the expiration date from a multi-channel guest, use:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"urn:scim:schemas:extension:slack:guest:1.0.expiration"
]
}
}
To convert a multi-channel guest to a full member, use:
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"urn:scim:schemas:extension:slack:guest:1.0"
]
}
}
To remove a specific attribute or sub-attributes, use the meta.attributes
request.
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": [
"roles",
"name.familyName",
"urn:scim:schemas:extension:enterprise:1.0.department"
]
}
}
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
.
externalId
attribute are not supported.
{
"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"
}
]
}
Sets a Slack user to deactivated. 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
POST /Users (Multi-Channel Guests)
Create a multi-channel guest user using the urn:scim:schemas:extension:slack:guest:1.0
attribute in one of the following two ways. The type
sub attribute is mandatory while the expiration
sub attribute is optional. The only valid value for the type
sub-attribute is "multi"
string. The expiration
date must be an ISO 8601 date time string.
urn:scim:schemas:extension:slack:guest:1.0
URI in the schemas
attribute.
Option 1
Specifies a multi-channel guest user account that expires on "11/30/2020 23:59:59 UTC".
"urn:scim:schemas:extension:slack:guest:1.0": {
"type": "multi",
"expiration": "2020-11-30T23:59:59Z"
}
Option 2
Specifies a multi-channel guest user account with no expiration date.
"urn:scim:schemas:extension:slack:guest:1.0": {
"type": "multi"
}
Example:
{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:enterprise:1.0",
"urn:scim:schemas:extension:slack:guest: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",
"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"
}
},
"urn:scim:schemas:extension:slack:guest:1.0": {
"type": "multi",
"expiration": "2020-11-30T23:59:59Z"
}
}
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
(max 1000) query parameters to paginate long lists of groups. Pagination will be required as of August 30, 2019.
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 (regular and/or multi-channel guest users) can be added to the group during creation by supplying the Slack user ID values in the members
array attribute. A maximum of 15,000 users per call can be added using this endpoint.
{
"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 (regular and/or multi-channel guest users) to be added or removed from the group with a single operation. A maximum of 15,000 users per call can be modified using this endpoint.
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. A maximum of 15,000 users per call can be updated using this endpoint.
{
"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 | present 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
Errors
Occasionally, interacting with our APIs will result in an error instead of the result you're expecting. Slack will make every attempt to respond with a descriptive error message that will help you figure out what went wrong and how to fix it.
Error | Description |
---|---|
addresses_invalid |
The addresses attribute provided is invalid. |
bad_email_address |
The email address provided does not exist or was poorly formatted. |
bad_endpoint |
The endpoint URL does not exist. |
cannot_decode_user_id |
The given user ID cannot be decoded. |
cannot_modify_owner |
A Workspace's ownership can not be modified via SCIM, please use the Slack admin. |
cannot_modify_gdpr |
Users who have had their personal information forgotten under GDPR can not be modified. |
cannot_disable_bot_user_with_scim |
The SCIM API can not be used to deactivate a bot user, this must be done via the bot admin. |
cannot_disable_primary_owner |
The primary owner of a Workspace can not be deactivated. If this user needs to be deactivated, please make another team member the primary owner first. |
email_empty |
The user's primary email is missing from the request. |
email_invalid |
The provided user email values are invalid. |
email_taken |
The provided user email value already exists. |
emails_invalid |
The emails attribute provided is invalid. |
failed_to_remove_users_for_linked_subteam |
An error occured when removing users from this IDP group. |
group_members_create_failed |
An error occurred during an update to a user group. |
group_member_max_exceeded |
The maximum number of members allowed in a group was exceeded (max users is 250k). Additional users cannot be added unless some are removed. |
group_creation_failed |
The request to create a user group has failed. |
groups_invalid |
The groups attribute provided is invalid. |
idp_group_linked_to_channels |
This IDP group is linked to one or more channels via admin.conversations.whitelist.add . You must call admin.conversations.whitelist.remove for each link before you can delete the group. |
improper_enterprise_schema_format |
The urn:scim:schemas:extension:enterprise:1.0.manager sub-attribute is missing the required managerId sub-attribute. |
incomplete_filter |
A malformed filter query has been specified. Please check that the filter are separated by a single space. filter=attribute eq "value" |
invalid_attribute_format |
A singular or multi-valued attribute has been specified with the wrong type. |
invalid_authentication |
There's a problem with the OAuth token. It may not have been granted the proper admin scope or may not have been installed by an administrator. The token may also be malformed or not properly sent via an Authorization header with a type of Bearer. |
invalid_display_name |
The provided display name is not allowed. |
invalid_emoji_not_allowed |
An attribute value contains an emoji. |
invalid_filter_group |
The provided filter contains a group that is malformed. |
invalid_name_maxlength |
The provided display name is not allowed because it exceeds the maximum allowable characters. |
invalid_name_specials |
The provided display name is not allowed because it is using invalid special characters such as @ . |
invalid_name_required |
Only a string containing spaces has been provided for both the givenName and familyName sub-attributes. |
invalid_query |
There's a problem with the filter parameter. Please check that the entities and operators are valid. |
invalid_request_payload |
The provided request payload may contain unsupported attributes or properties. |
invalid_reserved_word |
A reserved word has been specified in an attribute. |
invalid_starts_with_at |
The displayName attribute value provided starts with an @ |
invalid_sort_order |
The sortOrder parameter is not equal to ascending or descending . |
long_nickname |
The nickName parameter is longer than we allow. Max length is 21 characters. |
method_not_allowed |
Unsupported http method provided. Only GET , POST , PUT , PATCH and DELETE are supported. |
missing_authentication |
The authentication token is missing. |
missing_primary_email |
The request is attempting to remove the primary email without providing a replacement value. |
missing_schema_element |
The schemas attribute is missing from the request. |
missing_group_id |
The group ID has not been specified. |
missing_user_id |
The user ID has not been specified. |
no_filters |
The filter query parameter was provided but no filters were specified. |
no_such_group |
The group provided does not exist. |
no_such_group_members |
The group members provided do not exist. |
no_such_user |
The user provided does not exist. |
non_org_teams_only |
When using SCIM on an Enterprise Grid organization, the app must be installed on the organization, not individual workspaces. SCIM methods are called against the entire Grid organization. |
query_building_failed |
The provided filter did not translate to a proper database query. |
database_query_failure |
An error was encountered while executing a filter. |
password_change_not_allowed |
Updates to the password attribute via SCIM is prohibited. |
permission_denied |
The OAuth token has not been granted permission to perform the requested action. |
phoneNumbers_invalid |
The phoneNumbers attribute provided is invalid. |
photos_invalid |
The photos attribute provided is invalid. |
plus_teams_only |
The SCIM APIs are only available for Plus and Enterprise Grid plans. SCIM access is not available for Free and Standard plans. |
primary_owner_check_failure |
The primary owner of a Workspace within an organization can not deactivated. If this user needs to be deactivated, please make another team member the primary owner first. |
resource_locked |
The app is making too many requests over a short period of time for group update requests. Please make fewer requests to stay within Slack's rate limits. |
roles_invalid |
The roles attribute provided is invalid. |
too_many_requests |
The app is making too many requests over a short period of time. Please make fewer requests to stay within Slack's rate limits. |
too_many_users |
The request to update a Group contains more than 15,000 users. Please make the request with smaller batches of users. |
truncation_error |
The userName could not be truncated in an attempt to avoid a username conflict for the organization. |
unable_to_add_deleted_or_guest_to_group |
Deleted or guest users cannot be added to the Group. |
unable_to_create_team_profile_fields |
An error occurred during custom profile creation. |
unknown_user |
The user provided does not exist. |
unsupported_version |
The provided SCIM version is not supported. |
user_creation_failed |
The specified user already exists or an error was encountered when attempting to create a user. |
username_empty |
The userName attribute is empty when the user's endpoint is invoked via PUT or POST |
username_invalid |
The userName attribute provided is invalid. |
username_not_allowed |
The provided userName is reserved. |
username_required |
This method requires a username parameter. |
username_taken |
When provisioning a new user via SCIM, usernames must be unique and must also be unique from channel names. |
username_too_long |
The specified username is too long (max length is 21 characters). |
Concurrency
The SCIM API only allows one update to a user or group at a time (by locking the user or group while the update is in progress). Locking prevents overlapping requests, which can cause unpredictable results.
As a consequence, if you attempt to send multiple non-GET requests to the same user or group, and that user or group is still being updated from a previous request, you'll see a 429 HTTP response code. The 429 code will be returned with a retry-after header—wait for the time specified in that header to resend the request.
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
- 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.
- 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. - Slack does not store
type
foraddresses
. Thetype
field will be used to determine which address is the "primary address" if the request does not specify one, however thetype
is not stored. - Username values and channel name values must be unique and share the same namespace. For example, you can't have a username for
@general
if you also have a#general
channel in the Slack workspace. - There is a limit of 50 custom profile fields, which includes fields set via the SCIM API. If your request would cause more than 50 fields to exist, the call will fail with a
unable_to_create_team_profile_fields
error.