Sign in

SCIM 2.0

This reference focuses on how Steady API endpoints share information with System for Cross-domain Identity Management (SCIM) specific API calls.

This document specifically covers version 2.0 of the SCIM specification.

The SCIM protocol is an application-level REST protocol for provisioning and managing identity data on the web. The protocol supports creation, discovery, retrieval, and modification of core identity resources.

See below for references to the IETF standards RFCs.

SCIM User Operations

Determine if the User already exists

GET /Users

Check that the User object exists in our system through a GET method request with the filter=userName  parameter, which is the email address. This check is performed using the eq  (equal) operator.

In Steady, userName  is an email address and a unique identifier.

The requests should be of the form:

GET /scim/v2/<account_id>/Users?filter=userName%20eq%20%22test.user%40y.local%22&startIndex=1&count=100 HTTP/1.1 Authorization: <Authorization credentials>

We check the filter provided and returns an empty response if no Users match the filter criteria. For example:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 0,
"startIndex": 1,
"itemsPerPage": 0,
"Resources": []
}

Create the User

POST /Users

If the User object isn't found, then attempt to create it through a POST method request that contains the user's application profile. The request looks like the following:

POST /scim/v2/<account_id>/Users 
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "[email protected]",
"name": {
"givenName": "Test",
"familyName": "User"
},
"locale": "en",
"timezone": "America/New_York"
}

The response from the SCIM server contains the created User object:

HTTP/1.1 201 Created
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"userName": "[email protected]",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"locale": "en",
"timezone": "America/New_York",
"active": true,
"accountAdministrator": false
}

Steady optionally collects a custom accountAdministrator  boolean attribute for users. The request to create a user looks like the following:

POST /scim/v2/<account_id>/Users
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "[email protected]",
"name": {
"givenName": "Test",
"familyName": "User"
},
"locale": "en",
"timezone": "America/New_York",
"accountAdministrator": true
}

If the User object already exists in Steady, then the application will respond with an error schema. The response looks like the following:

HTTP/1.1 409 Conflict
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "User already exists in the database.",
"status": 409
}

Retrieve Users

GET /Users

When exporting User objects from the SCIM server, access the /Users  endpoint and process them page by page, using startIndex  , count  , and totalResults  as pagination references.


Use count=100  as the pagination reference to return up to 100 elements. If the value of totalResults  is higher than 100, then after finishing retrieving the first 100 resources, the startIndex  becomes startIndex+100  and should be passed as a query parameter along with count  in a new request to the /Users  endpoint.


A sample request to retrieve the Users:

GET /scim/v2/<account_id>/Users?startIndex=1&count=100 
Authorization: <Authorization credentials>

The response to this request is a JSON list of all the resources found in Steady for your account.

Retrieve a specific User

GET /Users/$userID

Run a GET method request to check if a specific User object still exists on the SCIM server. The request looks like the following:

GET /scim/v2/Users/23a35c27-23d3-4c03-b4c5-6443c09e7173
<Authorization credentials>

The response from the server is the User object:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"userName": "[email protected]",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"locale": "en",
"timezone": "America/New_York",
"active": true,
"accountAdministrator": false
"groups": [
{
"value": "77921c20-d48c-5e1b-bab1-3dac236e1143",
"display": "Alpha Team",
"teamLead": true
},
{
"value": "0c70a70b-ecb5-58dd-9caf-ed674db04b91",
"display": "Bravo Team",
"teamLead": false
}
]
}

Update a specific User (PUT)

Updating a User object refers to modifying an attribute in the user's application profile that is mapped to an attribute in the SCIM application.

Retrieve the User

GET /Users/$userID

To update a user, first make a GET method request to /Users/${userID}  and retrieve the body of the User object:

GET /scim/v2/<account_id>/Users/23a35c27-23d3-4c03-b4c5-6443c09e7173

When the SCIM server receives this request, it responds with the User object:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"userName": "[email protected]",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"locale": "en",
"timezone": "America/New_York",
"active": true,
"accountAdministrator": false
"groups": [
{
"value": "77921c20-d48c-5e1b-bab1-3dac236e1143",
"display": "Alpha Team",
"teamLead": true
},
{
"value": "0c70a70b-ecb5-58dd-9caf-ed674db04b91",
"display": "Bravo Team",
"teamLead": false
}
]
}

Update the User

PUT /Users/$userID

After the User object is retrieved from the SCIM server, modify the attributes that were changed and run a PUT method request with the new body to the /Users/${userID}  endpoint:

PUT /scim/v2/<account_id>/Users/23a35c27-23d3-4c03-b4c5-6443c09e7173
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "[email protected]",
"name": {
"givenName": "Test",
"familyName": "Person"
},
"locale": "en",
"timezone": "America/New_York",
"accountAdministrator": false
}

The response from the SCIM server will be the updated User object:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"userName": "[email protected]",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"locale": "en",
"timezone": "America/New_York",
"active": true,
"accountAdministrator": false
"groups": [
{
"value": "77921c20-d48c-5e1b-bab1-3dac236e1143",
"display": "Alpha Team",
"teamLead": true
},
{
"value": "0c70a70b-ecb5-58dd-9caf-ed674db04b91",
"display": "Bravo Team",
"teamLead": false
}
]
}

Deactivate Users

PUT (or PATCH) /Users/$userID

Send a request to your SCIM application to set the active  attribute to false  .

SCIM Group operations

Create Groups

POST /Groups

To create a Group object on the SCIM server, make a POST method request:

POST /scim/v2/<account_id>/Groups
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Test SCIMv2",
"members": [{ "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173" }]
}

When it receives this request, the SCIM server responds with the Group object as it would for a GET method request to the /Groups/${groupID}  :

HTTP/1.1 201 Created
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
"displayName": "Test SCIMv2",
"members": [
{
"value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"display": "Test User",
"teamLead": false
}
]
}

Steady optionally collects a custom teamLead  boolean attribute for Group members. The request to create a team lead member looks like the following:

POST /scim/v2/<account_id>/Groups
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Test SCIMv2",
"members": [
{ "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "teamLead": true }
]
}

Retrieve Groups

GET /Groups

When exporting Group objects from the SCIM server, access the /Groups  endpoint and process them page by page, using the startIndex  , count  , and totalResults  values for reference. Using a limit of count  results and an offset of startIndex  returns smaller groupings of resources in a request.

Use count=100  as the pagination reference to return up to 100 elements. If the value of totalResults  is higher than 100, then after finishing retrieving the first 100 resources, the startIndex  becomes startIndex+100  and is passed as a query parameter along with count  in a new request to the /Groups  endpoint.

A sample request to retrieve the Group objects from the SCIM application:

GET /scim/v2/<account_id>/Groups?startIndex=1&count=100 Authorization: <Authorization credentials>

The response to this request is a JSON list of all the Group objects found in the SCIM application.

Retrieve specific Groups

GET /Groups/$groupID

To run a GET method request on a specific ${groupID}  , for example to see if the Group object still exists on the SCIM server, the request looks like the following:

GET /scim/v2/<account_id>/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b Authorization: <Authorization credentials>

The response from the server is the Group object details:

HTTP/1.1 200 OK

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
"displayName": "Test SCIMv2",
"members": [
{
"value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"display": "Test User",
"teamLead": false
}
]
}

Update a specific Group

PUT /Groups/$groupID

Updates to existing groups are handled by a PUT method request to the SCIM application. The Group object must be already pushed out to the SCIM server.

PUT /scim/v2/<account_id>/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Updated Test SCIMv2",
"members": [
{ 
"value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"teamLead": true
}
]
}

The SCIM server response is to return the updated Group object:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
"displayName": "Updated Test SCIMv2",
"members": [
{
"value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"display": "Test User",
"teamLead": true
}
]
}

Update a specific Group’s name

PATCH /Groups/$groupID

Send a PATCH request with an Operation to replace the group’s display name:

PATCH /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b 
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:PatchOp"],
"Operations": [
{ 
"op": "Replace", 
"path": "displayName", 
"value": "New Name"
}
]
}

The SCIM server response is to return the updated Group object:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
"displayName": "New Name",
"members": [
{
"value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"display": "Test User",
"teamLead": false
}
]
}

Add members to a specific Group

PATCH /Groups/$groupID

Send a PATCH request with an Operation to add members:

PATCH /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b 
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"Operations": [
{ 
"op": "Add", 
"path": "members", 
"value": [
{ "value": "dc3d00c8-fd0b-4f4f-b362-e7c347cea531" }
] 
}
]
}

The SCIM server response is to return the updated Group object:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
"displayName": "Test SCIMv2",
"members": [
{
"value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
"display": "Test User",
"teamLead": false
},
{
"value": "dc3d00c8-fd0b-4f4f-b362-e7c347cea531",
"display": "Another User",
"teamLead": false
}
]
}

Remove members from a specific Group

PATCH /Groups/$groupID

Send a PATCH request with an Operation to remove members:

PATCH /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b 
Authorization: <Authorization credentials>

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"Operations": [
{ 
"op": "Remove", 
"path": "members", 
"value": [
{ "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173" }
] 
}
]
}

The SCIM server response is to return the updated Group object:

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
"displayName": "Test SCIMv2",
"members": [
{
"value": "dc3d00c8-fd0b-4f4f-b362-e7c347cea531",
"display": "Another User",
"teamLead": false
}
]
}

Delete a specific Group

DELETE /Groups/$groupID

DELETE /scim/v2/<account_id>/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b Authorization: <Authorization credentials>

The SCIM server returns an empty response:

HTTP/1.1 204 No Content

Resources