SCIM 2.0 API reference
Welcome to the new home of Slack developer docs!
We're still building and not all features are available quite yet. Enjoy this peek into the future!
Not ready for the future? Return to the past at api.slack.com.
The SCIM API is RESTful and the endpoint URLs are different than other Slack API endpoints.
| Endpoint | Description |
|---|---|
GET /ServiceProviderConfig | Returns Slack's configuration details for our SCIM API |
GET /ResourceTypes | Returns Slack's type of resources available |
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 |
GET /Users | Returns a paginated list of users |
GET /Users/<id> | Retrieves a single user resource |
POST /Users | Creates a user |
PATCH /Users/<id> | Updates an existing user resource, overwriting specified values |
PUT /Users/<id> | Updates an existing user resource, overwriting all values |
DELETE /Users/<id> | Sets a Slack user to deactivated |
GET /Groups/ | Returns a paginated list of groups |
GET /Groups/<id> | Retrieves a single group resource |
POST /Groups | Creates a new group |
PATCH /Groups/<id> | Updates an existing group resource |
PUT /Groups/<id> | Updates an existing group resource, overwriting all values |
DELETE /Groups/<id> | Permanently removes a group |
Service Provider Configuration
| Endpoint | Description |
|---|---|
GET /ServiceProviderConfigs | Returns Slack's configuration details for our SCIM API |
GET /ServiceProviderConfigs
Returns Slack's configuration details for our SCIM API, including which operations are supported.
Resource types
| Endpoint | Description |
|---|---|
GET /ResourceTypes | Returns Slack's configuration details for our SCIM API |
GET /ResourceTypes
Returns Slack's type of resources available.
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.
| Endpoint | Description |
|---|---|
GET /Schemas | Returns a list of Slack supported schemas along with Slack's configuration details |
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 |
Get /Schemas
Returns a list of Slack supported schemas along with Slack's configuration details.
GET /Schemas/Users
Returns Slack's configuration details for how users are formatted.
Multi-channel guest user schema
Provisioning multi-channel guest users with the SCIM API is only available to Enterprise Grid customers.
Slack also supports a custom extension, called urn:scim:schemas:extension:slack:guest:2.0:User, 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/v2/Schemas/Users payload.
GET /Schemas/Groups
Returns Slack's configuration details for how groups are formatted.
Users
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.
| Endpoint | Description |
|---|---|
GET /Users | Returns a paginated list of users |
GET /Users/{id} | Retrieves a single user resource |
POST /Users | Creates a user |
PATCH /Users/{id} | Updates an existing user resource, overwriting specified values |
PUT /Users/{id} | Updates an existing user resource, overwriting all values |
DELETE /Users/{id} | Sets a Slack user to deactivated |
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.
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.
| Slack Profile Field | SCIM Attribute | Attribute Type | Notes |
|---|---|---|---|
| Username | userName | Singular | Required |
| Full Name | name, familyName | Singular | |
| Nickname | nickName | Singular | |
| Display Name | displayName, userName | Singular | Support periods ., underscores _, and hyphens -. All other special characters are converted to underscores. Max of 80 characters. |
emails[0]['value'] | Multi-Valued | Required | |
| Profile URL | profileUrl | Singular | |
| Profile Photo | photos[0]['values'] | Multi-Valued | |
| Groups | groups | Multi-Valued | |
| Title | title | Singular | |
| Timezone | timezone | Singular | |
| Active | active | Singular | |
| Password | password | Singular | Never returned but can be used to set the initial password for a user if the team is not using an identity manager. |
| Start Date | profile.startDate | Singular | Date should be in the ISO 8601 format, such as 2024-04-10T00:00:00+0000. Must provide the urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User schema in request body. |
Slack will also create profile fields if the following SCIM attributes are present:
| Custom Profile Field | SCIM Attribute | Attribute Type |
|---|---|---|
| Addresses | addresses | Multi-Valued |
| City | addresses[primary]['locality'] | 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 |
| Manager | enterprise.manager.managerId | Singular |
| Organization | enterprise.organization | Singular |
| Phone | phoneNumbers[0]['values'] | Multi-Valued |
| Preferred Language | preferredLanguage | Singular |
| Roles | roles | Multi-Valued |
| Title | title | Singular |
| UserType | userType | Singular |
| Zip Code | addresses[primary]['postalCode'] | Singular |
GET /Users
Request
GET /scim/v2/Users?startIndex=1&count=1 HTTP/1.1
Host: api.slack.com
Accept: application/json
Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx
Response
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"id": "U123ABC456",
"externalId": "",
"meta": {
"created": "2022-05-27T15:19:18-07:00",
"location": "https://api.slack.com/scim/v2/Users/U123ABC456"
},
"userName": "jaydoe",
"nickName": "jaydoe",
"name": {
"givenName": "LAMBERT",
"familyName": "Halpert",
"honorificPrefix": "Mr."
},
"displayName": "Jay",
"profileUrl": "https://aDoeenterpriseorg.enterprise.slack.com/team/jaydoe",
"title": "asddddd",
"timezone": "America/New_York",
"active": true,
"emails": [
{
"value": "JayDoe@slack-corp.com",
"primary": true
},
{
"value": "KayDoe@slack-corp.com",
"primary": false
}
],
"photos": [
{
"value": "https://s3-us-west-2.amazonaws.com/slack-files-dev2/avatars/2022-08-09/1139718205683_4f58e078d159d6e22a79_192.png",
"type": "photo"
}
],
"addresses": [
{
"streetAddress": "340 N Washington Ave",
"locality": "Scranton",
"region": "PA",
"postalCode": "18503",
"country": "USA"
}
],
"phoneNumbers": [
{
"value": "+1 555 555 1234",
"type": "mobile"
},
{
"value": "+1 555 555 5678",
"primary": true
}
],
"userType": "Employee",
"roles": [
{
"value": "Sales Representative",
"primary": true
}
],
"preferredLanguage": "en_US",
"locale": "en_US",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "SR-005",
"costCenter": "123456789",
"organization": "Dunder Mifflin Paper Company, Inc",
"division": "Paper Distribution",
"department": "SALES",
"manager": {
"managerId": null
}
},
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User": {
"startDate": "2024-04-10T00:00:00+0000"
},
"groups": []
}
],
"totalResults": 1373,
"itemsPerPage": 1,
"startIndex": 1
}
GET /Users/<id>
Request
GET /scim/v2/Users/U123ABC456 HTTP/1.1
Host: api.slack.com
Accept: application/json
Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"id": "U123ABC456",
"externalId": "",
"meta": {
"created": "2022-08-16T12:49:47-07:00",
"location": "https://api.slack.com/scim/v2/Users/U123ABC456"
},
"userName": "doodoo",
"nickName": "doodoo",
"name": {
"givenName": "Jay",
"familyName": "Doe",
"honorificPrefix": "mr"
},
"displayName": "JayDoe7799979",
"profileUrl": "https://aDoeenterpriseorg.enterprise.slack.com/team/doodoo",
"title": "software developer",
"timezone": "America/Los_Angeles",
"active": true,
"emails": [
{
"value": "aDoe@slack-corp.com",
"primary": true
},
{
"value": "",
"primary": false
}
],
"photos": [
{
"value": "https://s3-us-west-2.amazonaws.com/slack-files-dev2/avatars/2023-02-19/1152719686210_6e95789b151a47536455_192.png",
"type": "photo"
}
],
"addresses": [
{
"streetAddress": "21 John Street",
"locality": "ON",
"region": "North America",
"postalCode": "M5G2Y4",
"country": "CA"
}
],
"phoneNumbers": [
{
"value": null,
"type": "mobile"
},
{
"value": "4168312999",
"primary": true
}
],
"userType": null,
"roles": [
{
"value": "role 1",
"primary": true
}
],
"preferredLanguage": null,
"locale": "en-US",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "123",
"costCenter": null,
"organization": "Org",
"division": "Div",
"department": "Dep",
"manager": {
"managerId": null
}
},
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User": {
"startDate": "2024-04-10T00:00:00+0000"
},
"groups": [
{
"value": "S123ABC456",
"display": "SCIM V2 Test Group"
}
]
}
POST /Users
Request
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"userName": "some_fake_username",
"nickName": "some_fake_username",
"name": {
"familyName": "Last",
"givenName": "First",
"honorificPrefix": "Ms."
},
"displayName": "First Last",
"profileUrl": "https://login.example.com/some_fake_username",
"emails": [
{
"value": "some_fake_user@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:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "701984",
"costCenter": "4130",
"organization": "Chicago Cubs",
"division": "Wrigley Field",
"department": "Tour Operations",
"manager": {
"managerId": "U123ABC456"
}
},
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User": {
"startDate": "2024-04-10T00:00:00+0000"
}
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"id": "U123ABC456",
"externalId": "",
"meta": {
"created": "2023-02-20T14:33:21-08:00",
"location": "https://api.slack.com/scim/v2/Users/U123ABC456"
},
"userName": "some_fake_username",
"nickName": "some_fake_username",
"name": {
"givenName": "First",
"familyName": "Last",
"honorificPrefix": "Ms."
},
"displayName": "First Last",
"profileUrl": "https://login.example.com/some_fake_username",
"title": "Tour Guide",
"timezone": "America/Chicago",
"active": true,
"emails": [
{
"value": "some_fake_user@email.com",
"primary": true
},
{
"value": "some_other@email.com",
"primary": false
}
],
"photos": [
{
"value": "https://secure.gravatar.com/avatar/a27ac11dd7b9af585d8fb54cbd0921e8.jpg?s=192&d=https%3A%2F%2Fslack.com%2Fdev-cdn%2Fv1676505571%2Fimg%2Favatars%2Fuser_shapes%2Fava_0018-192.png",
"type": "photo"
}
],
"addresses": [
{
"streetAddress": "1060 W Addison St",
"locality": "Chicago",
"region": "IL",
"postalCode": "60613",
"country": "USA"
}
],
"phoneNumbers": [
{
"value": "555-555-5555",
"type": "mobile"
},
{
"value": "555-555-4444",
"primary": true
}
],
"userType": "Employee",
"roles": [
{
"value": "Tech Lead",
"primary": true
}
],
"preferredLanguage": "en_US",
"locale": "en_US",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "701984",
"costCenter": "4130",
"organization": "Chicago Cubs",
"division": "Wrigley Field",
"department": "Tour Operations",
"manager": {
"managerId": "U123ABC456"
}
},
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User": {
"startDate": "2024-04-10T00:00:00+0000"
},
"groups": []
}
POST /Users (Multi-Channel Guest Users)
Request
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User"
],
"userName": "guestUser",
"displayName": "TestGuestUser",
"emails": [
{
"value": "some_guest_email@fake.com"
}
],
"urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User": {
"type": "multi"
}
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User"
],
"id": "U123ABC456",
"externalId": "",
"meta": {
"created": "2023-02-20T14:28:23-08:00",
"location": "https://api.slack.com/scim/v2/Users/U123ABC456"
},
"userName": "guestuser",
"nickName": "guestuser",
"name": {
"givenName": "TestGuestUser",
"familyName": ""
},
"displayName": "TestGuestUser",
"profileUrl": "https://aDoeenterpriseorg.enterprise.slack.com/team/guestuser",
"title": "",
"timezone": "America/Los_Angeles",
"active": true,
"emails": [
{
"value": "some_guest_email@fake.com",
"primary": true
}
],
"photos": [
{
"value": "https://secure.gravatar.com/avatar/2572f0dc723e0a547a14c5a472740cf6.jpg?s=192&d=https%3A%2F%2Fslack.com%2Fdev-cdn%2Fv1676505571%2Fimg%2Favatars%2Fuser_shapes%2Fava_0011-192.png",
"type": "photo"
}
],
"groups": [],
"urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User": {
"type": "multi"
}
}
PUT /Users/<id>
Request
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"externalId": "",
"userName": "updated_username",
"emails": [
{
"value": "some_updated_username@email.com",
"type": "work",
"primary": true
},
{
"value": "some_other@email.com",
"type": "home"
}
],
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"id": "U123ABC456",
"externalId": "",
"meta": {
"created": "2022-08-16T12:49:47-07:00",
"location": "https://api.slack.com/scim/v2/Users/U123ABC456"
},
"userName": "updated_username",
"nickName": "updated_username",
"name": {
"givenName": "Jay",
"familyName": "Doe",
"honorificPrefix": null
},
"displayName": "",
"profileUrl": "https://aDoeenterpriseorg.enterprise.slack.com/team/updated_username",
"title": "",
"timezone": "America/Los_Angeles",
"active": false,
"emails": [
{
"value": "some_updated_username@email.com",
"primary": true
},
{
"value": "some_other@email.com",
"primary": false
}
],
"photos": [
{
"value": "https://secure.gravatar.com/avatar/ca904af062782178167c3790cb28940a.jpg?s=192&d=https%3A%2F%2Fslack.com%2Fdev-cdn%2Fv1676505571%2Fimg%2Favatars%2Fuser_shapes%2Fava_0001-192.png",
"type": "photo"
}
],
"addresses": [
{
"streetAddress": null,
"locality": null,
"region": null,
"postalCode": null,
"country": null
}
],
"phoneNumbers": [
{
"value": null,
"type": "mobile"
},
{
"value": null,
"primary": true
}
],
"userType": null,
"roles": [
{
"value": null,
"primary": true
}
],
"preferredLanguage": null,
"locale": null,
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": null,
"costCenter": null,
"organization": null,
"division": null,
"department": null,
"manager": {
"managerId": null
}
},
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User": {
"startDate": null
}
"groups": []
}
PATCH /Users/<id>
Request
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber",
"value": "121"
},
{
"op": "add",
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter",
"value": "001919"
},
{
"op": "remove",
"path": "address"
}
]
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"id": "U123ABC456",
"externalId": "",
"meta": {
"created": "2022-08-16T12:49:47-07:00",
"location": "https://api.slack.com/scim/v2/Users/U123ABC456"
},
"userName": "updated_username",
"nickName": "updated_username",
"name": {
"givenName": "Jay",
"familyName": "Doe",
"honorificPrefix": null
},
"displayName": "",
"profileUrl": "https://aDoeenterpriseorg.enterprise.slack.com/team/updated_username",
"title": "",
"timezone": "America/Los_Angeles",
"active": false,
"emails": [
{
"value": "some_updated_username@email.com",
"primary": true
},
{
"value": "some_other@email.com",
"primary": false
}
],
"photos": [
{
"value": "https://secure.gravatar.com/avatar/ca904af062782178167c3790cb28940a.jpg?s=192&d=https%3A%2F%2Fslack.com%2Fdev-cdn%2Fv1676505571%2Fimg%2Favatars%2Fuser_shapes%2Fava_0001-192.png",
"type": "photo"
}
],
"addresses": [
{
"streetAddress": null,
"locality": null,
"region": null,
"postalCode": null,
"country": null
}
],
"phoneNumbers": [
{
"value": null,
"type": "mobile"
},
{
"value": null,
"primary": true
}
],
"userType": null,
"roles": [
{
"value": null,
"primary": true
}
],
"preferredLanguage": null,
"locale": null,
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "121",
"costCenter": "001919",
"organization": null,
"division": null,
"department": null,
"manager": {
"managerId": null
}
},
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User": {
"startDate": "2024-04-10T00:00:00+0000"
},
"groups": []
}
Using PATCH /Users/<id> with specific attributes
activate
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:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "active",
"op": "replace",
"value": true
}
]
}
userName
Updates to the userName attribute will also update the nickName attribute and vice versa.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "userName",
"op": "replace",
"value": "other_username"
}
]
}
nickName
Updates to the nickName attribute will also update the userName attribute and vice versa.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "nickName",
"op": "replace",
"value": "slack_username"
}
]
}
displayName
Updates a user's Slack display name profile field. The following request will update the user's handle to @First Last.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "displayName",
"op": "replace",
"value": "First Last"
}
]
}
title
Updates a user's title profile field.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "title",
"op": "replace",
"value": "Tour Guide"
}
]
}
userType
Updates a user's userType profile field.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "userType",
"op": "replace",
"value": "Employee"
}
]
}
preferredLanguage
Updates the user's preferred language profile field
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "preferredLanguage",
"op": "replace",
"value": "en_US"
}
]
}
locale
Updates the user's locale profile field.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "locale",
"op": "replace",
"value": "en_US"
}
]
}
timezone
Updates the user's timezone profile field.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "timezone",
"op": "replace",
"value": "America/Chicago"
}
]
}
emails
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:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "emails",
"op": "add",
"value": [
{
"value": "some@email.com",
"type": "work",
"primary": true
},
{
"value": "some_other@email.com",
"type": "home"
}
]
}
]
}
Alternatively, you can add a single email entry using
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "emails",
"op": "add",
"value": {
"value": "some_other@email.com",
"type": "home"
}
}
]
}
You can also replace a secondary email using the following
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "emails[primary eq false]",
"op": "replace",
"value": {
"value": "some_other_replaced@email.com",
"type": "work"
}
}
]
}
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:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "emails[primary eq false]",
"op": "remove"
}
]
}
or
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "emails[value eq \"some_other@email.com\"]",
"op": "remove"
}
]
}
The following request will only remove the secondary email.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "emails",
"op": "remove"
}
]
}
phoneNumbers
Only two user phone numbers are stored: the primaryPhone and mobilePhone. Updating numbers is done by setting one of the primary or type fields for each updated number.
In this example, 123-333-3333 is set as the primaryPhone.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "phoneNumbers",
"op": "add",
"value": {
"value": "123-333-3333",
"primary": true
}
}
]
}
In this example, 123-333-3333 is set as the mobilePhone.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "phoneNumbers",
"op": "add",
"value": [
{
"value": "123-333-3333",
"type": "work"
}
]
}
]
}
In this example, 222-222-2222 is set as the mobilePhone and 333-333-3333 is set as the primaryPhone.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "phoneNumbers",
"op": "add",
"value": [
{
"value": "222-222-2222",
"primary": false
},
{
"value": "333-333-3333",
"primary": true
}
]
}
]
}
The primary or secondary phone numbers may be deleted by specifying their respective values using the remove operation. The following request will delete all of the user's phone numbers.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "phoneNumbers[value eq \"333-333-3333\"]",
"op": "remove"
},
{
"path": "phoneNumbers[value eq \"222-222-2222\"]",
"op": "remove"
}
]
}
or
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "phoneNumbers",
"op": "remove"
}
]
}
The primary or secondary phone number value can be replaced using the “replace operation”. The following request will replace the phoneNumber value with 222-222-2222 to 111-111-111.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "phoneNumbers[value eq \"333-333-3333\"].value",
"op": "replace",
"value": "111-111-111"
}
]
}
photos
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:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "photos",
"op": "add",
"value": [
{
"value": "https://photos.example.com/profilephoto.jpg",
"primary": true
}
]
}
]
}
addresses
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:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "addresses",
"op": "add",
"value": [{
"streetAddress": "1060 W Addison St",
"locality": "Chicago",
"region": "IL",
"postalCode": "60613",
"country": "USA",
"primary": true
}]
}
]
}
To remove a user address, use the remove operation.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "addresses",
"op": "remove"
}
]
}
roles
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:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "roles",
"op": "add",
"value": [
{
"value": "Tech Lead",
"primary": true
}
]
}
]
}
or
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "roles",
"op": "add",
"value": ["Tech Lead"]
}
]
}
To remove a user's role, use the operation “remove”.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "roles",
"op": "remove"
}
]
}
name
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:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "name",
"op": "add",
"value": {
"familyName": "Last",
"givenName": "First",
"honorificPrefix": "Ms."
}
}
]
}
Otherwise, specify only the sub-attributes to update using the “replace” operation.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "name.givenName",
"op": "replace",
"value": "First"
}
]
}
To remove a specific name sub-attribute, use:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "name.honorificPrefix",
"op": "remove"
}
]
}
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
If the manager sub-attribute is specified, the managerId sub-attribute must be specified as well. The value for the managerId sub-attribute can be their valid Slack id, their primary email, or their userName attribute. Each request can use a different type of value for the managerId sub-attribute.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"op": "add",
"value": {
"employeeNumber": "701984",
"costCenter": "4130",
"organization": "Chicago Cubs",
"division": "Wrigley Field",
"department": "Tour Operations",
"manager": {
"managerId": "U123ABC456"
}
}
}
]
}
Otherwise, specify only the sub-attributes to update.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"op": "replace",
"value": {
"manager": {
"managerId": "U123ABC456"
}
}
}
]
}
To remove a specific urn:ietf:params:scim:schemas:extension:enterprise:2.0:User sub-attribute, use:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.manager.managerId",
"op": "remove"
}
]
}
To remove all of the urn:ietf:params:scim:schemas:extension:enterprise:2.0:User sub-attributes, use:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"op": "remove"
}
]
}
urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User
Provisioning multi-channel guest users with the SCIM API is only available to Enterprise Grid customers.
Converts a full member to a multi-channel guest, or converts a multi-channel guest to a full member.
Converting a full member to a multi-channel guest
If the full member is deactivated, this method will reactivate them on conversion.
To convert a full member to a multi-channel guest with an expiration date, use:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User",
"op": "add",
"value": {
"type": "multi",
"expiration": "2024-11-30T23:59:59Z"
}
}
]
}
To convert a full member to a multi-channel guest without an expiration date, use:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User",
"op": "add",
"value": {
"type": "multi"
}
}
]
}
To remove the expiration date from a multi-channel guest, use:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User.expiration",
"op": "remove"
}
]
}
Converting a multi-channel guest to a full member
If the multi-channel guest is deactivated, this method will reactivate them on conversion.
To convert a multi-channel guest to a full member, use:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"path": "urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User",
"op": "remove"
}
]
}
urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User
Updates the user's start date profile field.
{
"schemas": [
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User"
],
"urn:ietf:params:scim:schemas:extension:slack:profile:2.0:User": {
"startDate": "2024-04-10T00:00:00+0000"
},
}
DELETE /Users/<id>
Request
DELETE /scim/v2/Users/42 HTTP/1.1
Host: api.slack.com
Accept: application/json
Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx
Response
204
Groups
Groups are for organizing users in logical divisions across a workspace, such as by team or affinity.
| Endpoint | Description |
|---|---|
GET /Groups/ | Returns a paginated list of groups |
GET /Groups/{id} | Retrieves a single group resource |
POST /Groups | Creates a new group |
PATCH /Groups/{id} | Updates an existing group resource |
PUT /Groups/{id} | Updates an existing group resource, overwriting all values |
DELETE /Groups/{id} | Permanently removes a group |
Group attributes
Attributes are the details associated with a group.
| Slack Group Field | SCIM Attribute | Attribute Type | Required |
|---|---|---|---|
| Name | displayName | String | Required |
| Members | members | Multi-valued | Required |
GET /Groups
Request
GET /scim/v2/Groups?startIndex=1&count=1 HTTP/1.1
Host: api.slack.com
Accept: application/json
Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx
Response
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "S123ABC456",
"meta": {
"created": "2022-07-26T14:05:41-07:00",
"location": "https://api.slack.com/scim/v2/Groups/S123ABC456"
},
"displayName": "SOMETHING NEW",
"members": []
}
],
"totalResults": 15,
"itemsPerPage": 1,
"startIndex": 1
}
GET /Groups/<id>
Request
GET /scim/v2/Groups/S123ABC456
Host: api.slack.com
Accept: application/json
Authorization: Bearer xoxp-4956040672-4956040692-6476208902-xxxxxx
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "S123ABC456",
"meta": {
"created": "2023-02-10T07:36:51-08:00",
"location": "https://api.slack.com/scim/v2/Groups/S123ABC456"
},
"displayName": "Applications-600",
"members": [
{
"value": "U123ABC456",
"display": "Lexus Powlowski"
},
{
"value": "U123ABC456",
"display": "Porter Prosacco"
}
]
}
POST /Groups
Request
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Some Group Name",
"members": [
{
"value": "U123ABC456"
}
]
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "S123ABC456",
"meta": {
"created": "2023-02-20T15:10:03-08:00",
"location": "https://api.slack.com/scim/v2/Groups/S123ABC456"
},
"displayName": "Some Group Name",
"members": [
{
"value": "U123ABC456",
"display": "example"
}
]
}
PUT /Groups/<id>
Request
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Updated Group Name"
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "S123ABC456",
"meta": {
"created": "2023-02-20T15:10:03-08:00",
"location": "https://api.slack.com/scim/v2/Groups/S123ABC456"
},
"displayName": "Updated Group Name",
"members": []
}
PATCH /Groups/<id>
Request
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "replace",
"path": "members",
"value": [
{
"value": "U123ABC456"
},
{
"value": "U999ABC456"
}
]
}
]
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "S123ABC456",
"meta": {
"created": "2023-02-20T15:10:03-08:00",
"location": "https://api.slack.com/scim/v2/Groups/S123ABC456"
},
"displayName": "Updated Group Name",
"members": [
{
"value": "U123ABC456",
"display": "Jay Doe"
},
{
"value": "U222ABC222",
"display": "Kay Doe"
}
]
}
Remove all existing members
Request
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "remove",
"path": "members"
}
]
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "S123ABC456",
"meta": {
"created": "2023-02-20T15:10:03-08:00",
"location": "https://api.slack.com/scim/v2/Groups/S123ABC456"
},
"displayName": "Updated Group Name",
"members": []
}
DELETE /Groups/<id>
Request
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "remove",
"path": "members"
}
]
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "S123ABC456",
"meta": {
"created": "2023-02-20T15:10:03-08:00",
"location": "https://api.slack.com/scim/v2/Groups/S123ABC456"
},
"displayName": "Updated Group Name",
"members": []
}
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_make_user_guest | Admins, Owners and Primary owners cannot be made guests via SCIM. |
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 occurred 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 | 15k is the recommended limit for IDP groups, The maximum is 4k for user groups. 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.restrictAccess.addGroup. You must call admin.conversations.restrictAccess.removeGroup for each link before you can delete the group. |
improper_enterprise_schema_format | The urn:scim:schemas:extension:enterprise:2.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. Only send the display name from your IDP upon account creation (not upon subsequent updates or to sync to a Slack account), or disable the Allow users to change their display name setting. |
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). |
Example error
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"detail": "missing_schema_element",
"status": 400
}
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.