This reference focuses on how Status Hero 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 Status Hero, 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": "test.user@yourco.local",
"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": "test.user@yourco.local",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "test.user@yourco.local"
}
],
"locale": "en",
"timezone": "America/New_York",
"active": true,
"accountAdministrator": false
}
Status Hero 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": "test.user@yourco.local",
"name": {
"givenName": "Test",
"familyName": "User"
},
"locale": "en",
"timezone": "America/New_York",
"accountAdministrator": true
}
If the User object already exists in Status Hero, 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 Status Hero 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": "test.user@yourco.local",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "test.user@yourco.local"
}
],
"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": "test.user@yourco.local",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "test.user@yourco.local"
}
],
"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": "test.person@yourco.local",
"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": "test.user@yourco.local",
"name": {
"givenName": "Test",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "test.user@yourco.local"
}
],
"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
}
]
}
Status Hero 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:Group"],
"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