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 <billing@screensteps.com>.
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/UsersAuthorization
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] | |
| userType | User role. Possible values are admin, editor, learner, and reader. |
Example requests
List users
Request
GET /api/scim/v1/UsersResponse
{
"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": "example@mail.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [
{
"value": "3936",
"display": "Example Group"
}
],
"userType": "learner"
},
{...}
]
}
Show a user
Request
GET /api/scim/v1/Users/:idResponse
{
"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": "mail@example.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [],
"userType": "reader",
"urn:scim:screensteps:schema:1.0": {
"editableSites": [
{
"value": "1",
"canPublish": true,
"canDelete": true,
"fullAccess": true,
"canModerateComments": true
}
]
}
}
Find a user by email address
Request
This will find a user with the email example@mail.com.
GET /api/scim/v1/Users?filter=userName eq "example@mail.com"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": "example@mail.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [
{
"value": "3936",
"display": "Example Group"
}
],
"userType": "learner"
}
]
}
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": "mail@example.com",
"name": {
"givenName": "John",
"familyName": "Doe",
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true
}
],
"remote_authentication_user": true
}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": "mail@example.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [],
"userType": "reader"
}
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": "mail@example.com",
"name": {
"givenName": "James",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [
{
"value": "3936",
"display": "Authentication Group (OneLogin)"
}
],
"userType": "reader",
"remote_authentication_user": true
}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": "mail@example.com",
"name": {
"givenName": "James",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [],
"userType": "reader"
}
Updating editableSites for an Editor user (beta)
This is a beta feature. Please contact support@screensteps.com 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": "mail@example.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [],
"userType": "editor",
"urn:scim:screensteps:schema:1.0": {
"editableSites": [
{
"value": "1",
"canPublish": true,
"canDelete": true,
"fullAccess": true,
"canModerateComments": true
}
]
}
}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": "mail@example.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [],
"userType": "reader",
"urn:scim:screensteps:schema:1.0": {
"editableSites": [
{
"value": "1",
"operation": "delete"
}
]
}
}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
Reactivate a user
Request
PATCH /api/scim/v1/Users/:id
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"active": true
}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": "mail@example.com",
"name": {
"givenName": "James",
"familyName": "Doe"
},
"timezone": "Eastern Time (US & Canada)",
"active": true,
"emails": [
{
"value": "mail@example.com",
"primary": true,
"type": "work"
}
],
"groups": [],
"userType": "reader"
}
List groups
Request
GET /api/scim/v1/GroupsResponse
{
"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"
}
]
},
...
Create a group
Request
POST /api/scim/v1/Groups
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "My Group"
}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": []
}
Add a user to a group
Request
PATCH /api/scim/v1/Groups/:id
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"members": [
{ "value": 115659 }
]
}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"
}
]
}
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"
}
]
}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": []
}
Remove all users in a group
Request
PATCH /api/scim/v1/Groups/:id
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"meta": {
"attributes": ["members"]
}
}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": []
}
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,
}
]
}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"
}
]
}
Update the group title
Request
PATCH /api/scim/v1/Groups/:id
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "New name"
}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"
}
]
}
Delete a group
Request
DELETE /api/scim/v1/Groups/:id
0 Comments
Add your comment