How to Use the SCIM User Provisioning API

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 eq "[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

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

Single Sign-on

Other Resources

Recently Updated Articles

Overview

API Endpoints

Authorization

Pagination (startIndex)

Supported fields

Example requests

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Add an editableSite

Remove an editableSite

Changing userType

Request

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

0 Comments

Add your comment