ScreenSteps

How to Use the SCIM User Provisioning API

Updated on

Workflows are not supported in your browser.
Please use a recent version of Chrome, Edge, Firefox or Safari to display this page.

This feature is only available to users on our Enterprise plan. If you're interested in upgrading to an Enterprise plan, please reach out to us at <[email protected]>.

If you are managing users through the SCIM API you may also be interested in How to manage user roles via user groups

Rate Limiting

ScreenSteps will impose a rate limit of 300 requests/minute. If you exceed this limit you will receive a 429 response. The JSON body will a retry_in value that will tell you how many seconds you need to wait to retry your request.

Which SCIM version are you using? Version 1 should not be used for new development and the documentation is only maintained as a reference for existing applications.

Overview

The ScreenSteps SCIM implementation follows standard SCIM conventions for:

  • Creating users
  • Updating users
  • Deleting users
  • Creating groups
  • Adding/removing users from groups
  • Deleting groups

API Endpoints

API endpoints are found at /api/scim/v2/Users and /api/scim/v2/Groups.

The full URL will include your account domain. For example:

https://my_account.screenstepslive.com/api/scim/v2/Users

Authorization

Authorization is done with an Authorization: Bearer {value} Header Parameter.

You should include an account API token as the Bearer value.

Supported fields

ScreenSteps will map the following SCIM values to users in ScreenSteps.

SCIM Value ScreenSteps User Value
id public_id
externalId external_id
userName login: Usually this is the user email. If your system is using SAML authentication with ScreenSteps they will be logged in via their email address.
name, { givenName, familyName } first_name and last_name
emails[0], { value }
 email
userType User role. Possible values are admin, editor, and reader.

For groups, the following values are mapped to groups.

SCIM Value
 ScreenSteps Group Value
id
 public_id
externalId
 external_id
displayName
 name
members [ {value}, {value}, ... ]
 Users in group. For each hash in the array, each value should be the ID for the user in the external system.

Pagination (startIndex)

List results will be paginated. The following keys will be present:

"totalResults": 220,

"itemsPerPage": 50,   

"startIndex": 1,

If you would like to get the additional results, pass in a startIndex query parameter with the offset you would like to use.

For example, to get the 2nd page of users you would use the following query if the itemsPerPage were 50:

/api/scim/v2/Users?startIndex=51

Example requests

List users
Request 
GET /api/scim/v2/Users
Click to copy
Response 
HTTP/1.1 200 OK

{
  "totalResults": 10,
  "itemsPerPage": 50,
  "startIndex": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "20beb8a5a8c93907",
      "externalId": "john_doe",
      "meta": {
        "created": "2018-03-08T12:03:47.000-05:00",
        "location": "https://scim-example.screenstepslive.com/api/scim/v2/Users/20beb8a5a8c93907"
      },
      "userName": "[email protected]",
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      },
      "timezone": "Eastern Time (US & Canada)",
      "active": true,
      "emails": [
        {
          "value": "[email protected]",
          "primary": true,
          "type": "work"
        }
      ],
      "groups": [
        {
          "value": "cb7e6c812dea1f3f",
          "display": "Example Group"
        }
      ],
      "userType": "reader"
    },
    {...}
  ]
}
Click to copy
Show a user
Request

The :id value is the id that ScreenSteps returned in the Create user response.

GET /api/scim/v2/Users/:id
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "4e3646d2187285a4",
  "externalId": "john_doe",
  "meta": {
    "created": "2018-05-16T08:52:44.000-04:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Users/4e3646d2187285a4"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "reader"
}
Click to copy
Find a user

You can search for a user on the following fields:

  • userName - searches the login property in ScreenSteps.
  • externalId - searches for a user with an externalId that matches the IDP id.
  • name.familyName - searches on the user's last name in ScreenSteps.
  • name.givenName - searches on the user's first name in ScreenSteps.
  • userType - searches on the user's role in ScreenSteps.
Request

This will find a user with the login [email protected] by using the userName query parameter.

 

GET /api/scim/v2/Users?filter=userName%20eq%20"[email protected]"
Click to copy
Response 
HTTP/1.1 200 OK

{
  "totalResults": 1,
  "itemsPerPage": 50,
  "startIndex": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "b7ee05a941f7af92",
      "externalId": "john_doe",
      "meta": {
        "created": "2018-03-08T12:03:47.000-05:00",
        "location": "https://scim-example.screenstepslive.com/api/scim/v2/Users/b7ee05a941f7af92"
      },
      "userName": "[email protected]",
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      },
      "timezone": "Eastern Time (US & Canada)",
      "active": true,
      "emails": [
        {
          "value": "[email protected]",
          "primary": true,
          "type": "work"
        }
      ],
      "groups": [
        {
          "value": "3936",
          "display": "Example Group"
        }
      ],
      "userType": "reader"
    }
  ]
}
Click to copy
Create a user
Request

If externalId is included in the payload then ScreenSteps will look for a user in the ScreenSteps system with a matching externalId.

If externalId is NOT included in the payload then ScreenSteps will look for a user with a matching email, and if not found, a matching userName.

In either of the above cases, if a user is found that user will be returned rather than creating a new user.

The remote_authentication_user parameter is optional and defaults to true. If you pass in false then you must provide a valid password parameter as well. This is because the password will be managed by ScreenSteps rather than a Single Sign-on Identity Provider.

POST /api/scim/v2/Users

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "john_doe",
  "userName": "[email protected]",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true
    }
  ],
  "remote_authentication_user": true
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "4e3646d2187285a4",
  "externalId": "john_doe",
  "meta": {
    "created": "2018-05-16T08:50:18.005-04:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Users/4e3646d2187285a4"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "reader"
}
Click to copy
Update a user
Request

The remote_authentication_user parameter is optional and defaults to true. If you pass in false then you must provide a valid password parameter as well. This is because the password will be managed by ScreenSteps rather than a Single Sign-on Identity Provider.

PUT /api/scim/v2/Users/:id

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "[email protected]",
  "name": {
    "givenName": "James",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "userType": "reader",
  "remote_authentication_user": true
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "4e3646d2187285a4",
  "externalId": "john_doe",
  "meta": {
    "created": "2018-05-16T08:52:44.000-04:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Users/4e3646d2187285a4"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "James",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "reader"
}
Click to copy
Delete a user
Request 
DELETE /api/scim/v2/Users/:id
Click to copy
Response 
HTTP/1.1 204 No Content
Click to copy
Deactivate a user
Request 
PATCH /api/scim/v2/Users/:id

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "active",
      "value": false
    }
  ]
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "5eb8357a5bb2b1e5",
  "externalId": null,
  "meta": {
    "created": "2018-05-16T07:52:44.000-05:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Users/5eb8357a5bb2b1e5"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "James",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": false,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "reader"
}
Click to copy
Reactivate a user
Request 
PATCH /api/scim/v2/Users/:id

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "active",
      "value": true
    }
  ]
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "5eb8357a5bb2b1e5",
  "externalId": null,
  "meta": {
    "created": "2018-05-16T07:52:44.000-05:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Users/5eb8357a5bb2b1e5"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "James",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "reader"
}
Click to copy
List groups
Request 
GET /api/scim/v2/Groups
Click to copy
Response 
HTTP/1.1 200 OK

{
  "totalResults": 4,
  "itemsPerPage": 50,
  "startIndex": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "59430aafe440f4cd",
      "meta": {
        "created": "2018-03-08T11:24:58.000-05:00",
        "location": "https://scim-example.screenstepslive.com/api/scim/v2/Groups/59430aafe440f4cd"
      },
      "displayName": "My Group",
      "members": [
        {
          "value": "53241c6c26473138",
          "display": Jane Doe"
        }
      ]
    },
    {...}
  ]
}
Click to copy
Create a group
Request 
POST /api/scim/v2/Groups

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "My Group"
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "59430aafe440f4cd",
  "meta": {
    "created": "2018-05-16T09:03:54.801-04:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Groups/59430aafe440f4cd"
  },
  "displayName": "My Group",
  "members": []
}
Click to copy
Add users to a group
Request 
PATCH /api/scim/v2/Groups/:id

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Add",
      "path": "members",
      "value": [
        {
          "value": "47c07a887900c1e3"
        },
        {
          "value": "2de057f5a7b2dd3a"
        }
      ]
    }
  ]
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "bcc958d5a92d3cc6",
  "meta": {
    "created": "2018-05-16T16:03:54.000+03:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Groups/bcc958d5a92d3cc6"
  },
  "displayName": "My Group",
  "members": [
    {
      "value": "47c07a887900c1e3",
      "display": "Jane Doe"
    },
    {
      "value": "2de057f5a7b2dd3a",
      "display": "James Doe"
    }
  ]
}
Click to copy
Remove a user from a group
Request 
PATCH /api/scim/v2/Groups/:id

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Remove",
      "path": 'members',
      "value": [
        {
          "value": "47c07a887900c1e3"
        }
      ]
    }
  ]
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "bcc958d5a92d3cc6",
  "meta": {
    "created": "2018-05-16T16:03:54.000+03:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Groups/bcc958d5a92d3cc6"
  },
  "displayName": "My Group",
  "members": []
}
Click to copy
Remove all users in a group
Request 
PATCH /api/scim/v2/Groups/:id

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "members",
      "value": []
    }
  ]
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "bcc958d5a92d3cc6",
  "meta": {
    "created": "2018-05-16T16:03:54.000+03:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Groups/bcc958d5a92d3cc6"
  },
  "displayName": "My Group",
  "members": []
}
Click to copy
Replace all users in a group

This request will remove all existing members from the group and replace them with the users included in the value parameter underneath the path members.

Request 
PATCH /api/scim/v2/Groups/:id

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "members",
      "value": [
        { 
          "value": "2ac048635694fa5a"
        },
        {
          "value": "14e778d7b8787667"
        }
      ]
    }
  ]
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "c57b77cd1bb48d47",
  "meta": {
    "created": "2018-05-16T16:03:54.000+03:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Groups/c57b77cd1bb48d47"
  },
  "displayName": "My Group",
  "members": [
    {
      "value": "2ac048635694fa5a",
      "display": "James Doe"
    },
    {
      "value": "14e778d7b8787667",
      "display": "Jane Doe"
    }
  ]
}
Click to copy
Update the group title
Request 
PATCH /api/scim/v2/Groups/:id

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "displayName",
      "value": "New name"
    }
  ]
}
Click to copy
Response 
HTTP/1.1 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "c57b77cd1bb48d47",
  "meta": {
    "created": "2018-05-16T16:03:54.000+03:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v2/Groups/c57b77cd1bb48d47"
  },
  "displayName": "New name",
  "members": [
    {
      "value": "2ac048635694fa5a",
      "display": "James Doe"
    }
  ]
}
Click to copy
Delete a group
Request 
DELETE /api/scim/v2/Groups/:id
Click to copy
Response 
HTTP/1.1 204 No Content
Click to copy

Overview

The ScreenSteps SCIM implementation follows standard SCIM conventions for:

  • Creating users
  • Updating users
  • Deactivating users
  • Creating groups
  • Adding/Removing users from groups

API Endpoints

API endpoints are found at /api/scim/v1/Users and /api/scim/v1/Groups.

The full URL will include your account domain. For example:

https://my_account.screenstepslive.com/api/scim/v1/Users

Authorization

Authorization is done with an Authorization: Bearer {value} Header Parameter.

You should include an account API token as the Bearer value.

Pagination (startIndex)

List results will be paginated. The following keys will be present:

"totalResults": 220, "itemsPerPage": 50,    "startIndex": 1,

If you would like to get the additional results, pass in a startIndex query parameter with the offset you would like to use.

For example, to get the 2nd page of users you would use the following query if the itemsPerPage were 50:

/api/scim/v1/Users?startIndex=51

Supported fields

ScreenSteps will map the following SCIM values to users in ScreenSteps.

SCIM Value ScreenSteps User Value
id id
external_id ID for user in your external system
userName login: Usually this is the user email. If your system is using SAML authentication with ScreenSteps they will be logged in via their email address.
name, { givenName, familyName } first_name and last_name
timezone timezone
emails[0] email
userType User role. Possible values are admin, editor, learner, and reader.

Example requests

List users
Request 
GET /api/scim/v1/Users
Click to copy
Response 
{
	"totalResults": 10,
	"itemsPerPage": 50,
	"startIndex": 1,
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"Resources": [
		{
			"schemas": [
				"urn:scim:schemas:core:1.0"
			],
			"id": "108063",
			"externalId": null,
			"meta": {
				"created": "2018-03-08T12:03:47.000-05:00",
				"location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/108063"
			},
			"userName": "[email protected]",
			"name": {
				"givenName": "John",
				"familyName": "Doe"
			},
			"timezone": "Eastern Time (US & Canada)",
			"active": true,
			"emails": [
				{
					"value": "[email protected]",
					"primary": true,
					"type": "work"
				}
			],
			"groups": [
				{
					"value": "3936",
					"display": "Example Group"
				}
			],
			"userType": "learner"
		},
		{...}
	]
}
Click to copy
Show a user
Request 
GET /api/scim/v1/Users/:id
Click to copy
Response 
{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:screensteps:schema:1.0"
  ],
  "id": "115659",
  "externalId": null,
  "meta": {
    "created": "2018-05-16T08:52:44.000-04:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/115659"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "reader",
  "urn:scim:screensteps:schema:1.0": {
    "editableSites": [
      {
        "value": "1",
        "canPublish": true,
        "canDelete": true,
        "fullAccess": true,
        "canModerateComments": true
      }
    ]
  }
}
Click to copy
Find a user by email address
Request

This will find a user with the email [email protected].

 

GET /api/scim/v1/Users?filter=userName%20eq%20"[email protected]"
Click to copy
Response 
{
	"totalResults": 1,
	"itemsPerPage": 50,
	"startIndex": 1,
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"Resources": [
		{
			"schemas": [
				"urn:scim:schemas:core:1.0"
			],
			"id": "108063",
			"externalId": null,
			"meta": {
				"created": "2018-03-08T12:03:47.000-05:00",
				"location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/108063"
			},
			"userName": "[email protected]",
			"name": {
				"givenName": "John",
				"familyName": "Doe"
			},
			"timezone": "Eastern Time (US & Canada)",
			"active": true,
			"emails": [
				{
					"value": "[email protected]",
					"primary": true,
					"type": "work"
				}
			],
			"groups": [
				{
					"value": "3936",
					"display": "Example Group"
				}
			],
			"userType": "learner"
		}
	]
}
Click to copy
Create a user
Request

If externalId is included in the payload then ScreenSteps will look for a user in the ScreenSteps system with a matching externalId.

If externalId is NOT included in the payload then ScreenSteps will look for a user with a matching email, and if not found, a matching userName.

In either of the above cases, if a user is found that user will be returned rather than creating a new user.

The remote_authentication_user parameter is optional and defaults to true. If you pass in false then you must provide a valid password parameter as well. This is because the password will be managed by ScreenSteps rather than a Single Sign-on Identity Provider.

POST /api/scim/v1/Users

{
   "schemas": [
     "urn:scim:schemas:core:1.0"
   ],
   "externalId": null,
   "userName": "[email protected]",
   "name": {
     "givenName": "John",
     "familyName": "Doe",
   },
   "timezone": "Eastern Time (US & Canada)",
   "active": true,
   "emails": [
     {
       "value": "[email protected]",
       "primary": true
     }
   ],
   "remote_authentication_user": true
 }
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "115658",
	"externalId": null,
	"meta": {
		"created": "2018-05-16T08:50:18.005-04:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/115658"
	},
	"userName": "[email protected]",
	"name": {
		"givenName": "John",
		"familyName": "Doe"
	},
	"timezone": "Eastern Time (US & Canada)",
	"active": true,
	"emails": [
		{
			"value": "[email protected]",
			"primary": true,
			"type": "work"
		}
	],
	"groups": [],
	"userType": "reader"
}
Click to copy
Update a user
Request

The remote_authentication_user parameter is optional and defaults to true. If you pass in false then you must provide a valid password parameter as well. This is because the password will be managed by ScreenSteps rather than a Single Sign-on Identity Provider.

PUT /api/scim/v1/Users/:id

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "userName": "[email protected]",
  "name": {
    "givenName": "James",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [
    {
      "value": "3936",
      "display": "Authentication Group (OneLogin)"
    }
  ],
  "userType": "reader",
  "remote_authentication_user": true
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "115659",
	"externalId": null,
	"meta": {
		"created": "2018-05-16T08:52:44.000-04:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/115659"
	},
	"userName": "[email protected]",
	"name": {
		"givenName": "James",
		"familyName": "Doe"
	},
	"timezone": "Eastern Time (US & Canada)",
	"active": true,
	"emails": [
		{
			"value": "[email protected]",
			"primary": true,
			"type": "work"
		}
	],
	"groups": [],
	"userType": "reader"
}
Click to copy
Updating editableSites for an Editor user (beta)

This is a beta feature. Please contact [email protected] to have this enabled on your account.

Users who have a userType of editor must be assigned to specific sites that they can edit. In addition they can be assigned different permissions for those sites. Permissions include:

  • canPublish - Allows publishing content
  • canDelete - Allows deleting content
  • canModerateComments - Allows comment moderation
  • fullAccess - Allows all privileges on the site. Setting this to true overrides all other value

This can be done when creating a user or when updating a user. The examples below just show the request when updating a user, but the same JSON would work for creating a user.

Add an editableSite 
PUT /api/scim/v1/Users/:id
{ 
 "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:screensteps:schema:1.0"
  ],
  "id": "115659",
  "externalId": null,
  "meta": {
    "created": "2018-05-16T08:52:44.000-04:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/115659"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "editor",
  "urn:scim:screensteps:schema:1.0": {
    "editableSites": [
      {
        "value": "1",
        "canPublish": true,
        "canDelete": true,
        "fullAccess": true,
        "canModerateComments": true
      }
    ]
  }
}
Click to copy

The value is the id of the site you want to give them access to.

Remove an editableSite

To remove an editableSite you will add an operation key to the editableSite object. See below.

PUT /api/scim/v1/Users/:id
{ 
 "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:screensteps:schema:1.0"
  ],
  "id": "115659",
  "externalId": null,
  "meta": {
    "created": "2018-05-16T08:52:44.000-04:00",
    "location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/115659"
  },
  "userName": "[email protected]",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "timezone": "Eastern Time (US & Canada)",
  "active": true,
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "groups": [],
  "userType": "reader",
  "urn:scim:screensteps:schema:1.0": {
    "editableSites": [
      {
        "value": "1",
        "operation": "delete"
      }
    ]
  }
}
Click to copy
Changing userType

If you change the userType to anything but an editor, all editableSites will be removed from the user.

Delete (deactivate) a user
Request 
DELETE /api/scim/v1/Users/:id
Click to copy
Reactivate a user
Request 
PATCH /api/scim/v1/Users/:id

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "active": true
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "115659",
	"externalId": null,
	"meta": {
		"created": "2018-05-16T07:52:44.000-05:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Users/115659"
	},
	"userName": "[email protected]",
	"name": {
		"givenName": "James",
		"familyName": "Doe"
	},
	"timezone": "Eastern Time (US & Canada)",
	"active": true,
	"emails": [
		{
			"value": "[email protected]",
			"primary": true,
			"type": "work"
		}
	],
	"groups": [],
	"userType": "reader"
}
Click to copy
List groups
Request 
GET /api/scim/v1/Groups
Click to copy
Response 
{
	"totalResults": 4,
	"itemsPerPage": 50,
	"startIndex": 1,
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"Resources": [
		{
			"schemas": [
				"urn:scim:schemas:core:1.0"
			],
			"id": "3936",
			"meta": {
				"created": "2018-03-08T11:24:58.000-05:00",
				"location": "https://scim-example.screenstepslive.com/api/scim/v1/Groups/3936"
			},
			"displayName": "My Group",
			"members": [
				{
					"value": "3936",
					"display": Jane Doe"
				}
			]
		},
...
Click to copy
Create a group
Request 
POST /api/scim/v1/Groups

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "displayName": "My Group"
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "4078",
	"meta": {
		"created": "2018-05-16T09:03:54.801-04:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Groups/4078"
	},
	"displayName": "My Group",
	"members": []
}
Click to copy
Add a user to a group
Request 
PATCH /api/scim/v1/Groups/:id

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
	"members": [
		{ "value": 115659 }
	]
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "4078",
	"meta": {
		"created": "2018-05-16T16:03:54.000+03:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Groups/4078"
	},
	"displayName": "My Group",
	"members": [
		{
			"value": "4078",
			"display": "James Doe"
		}
	]
}
Click to copy
Remove a user from a group
Request 
PATCH /api/scim/v1/Groups/:id

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
	"members": [
		{ 
			"value": 115659,
			"operation": "delete"
		}
	]
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "4078",
	"meta": {
		"created": "2018-05-16T16:03:54.000+03:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Groups/4078"
	},
	"displayName": "My Group",
	"members": []
}
Click to copy
Remove all users in a group
Request 
PATCH /api/scim/v1/Groups/:id

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "meta": {
     "attributes": ["members"]
   }
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "4078",
	"meta": {
		"created": "2018-05-16T16:03:54.000+03:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Groups/4078"
	},
	"displayName": "My Group",
	"members": []
}
Click to copy
Replace all users in a group

This request will remove all existing members from the group and replace them with the users in the members parameter.

Request 
PUT /api/scim/v1/Groups/:id

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
	"members": [
		{ 
			"value": 115659,
		}
	]
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "4078",
	"meta": {
		"created": "2018-05-16T16:03:54.000+03:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Groups/4078"
	},
	"displayName": "My Group",
	"members": [
		{
			"value": "4078",
			"display": "James Doe"
		}
	]
}
Click to copy
Update the group title
Request 
PATCH /api/scim/v1/Groups/:id

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "displayName": "New name"
}
Click to copy
Response 
{
	"schemas": [
		"urn:scim:schemas:core:1.0"
	],
	"id": "4078",
	"meta": {
		"created": "2018-05-16T16:03:54.000+03:00",
		"location": "https://scim-example.screenstepslive.com/api/scim/v1/Groups/4078"
	},
	"displayName": "New name",
	"members": [
		{
			"value": "4078",
			"display": "James Doe"
		}
	]
}
Click to copy
Delete a group
Request 
DELETE /api/scim/v1/Groups/:id
Click to copy
Congratulations, you are done!

0 Comments

Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Other Resources

Recently Updated Articles

More Recently Updated Articles
Still Need Help? Contact Us