Managing users via the SCIM API

OVERVIEW

The Assure SCIM API can be used to automate the processes of managing User and Person Register records in Assure. The API is accessed via the internet as a secure RESTful API which is widely supported by integration platforms, ETL tools, and all programming and scripting languages, so it can be easily set up to integrate with external systems. Making use of the SCIM API requires a level of technical expertise, so this is typically something that a company’s IT function would handle. 

The API functionality must be enabled by the Evotix team before you can use it. Please contact your CDM (Customer Development Manager) or CSM (Customer Success Manager) should you be interested in procuring this feature.

SETTING UP THE API

• Request Access - Please contact your Customer Development Manager or Customer Success manager to request access. 
• Generate API Keys - You can create and manage your API authentication keys at any time in Assure. Details can be found in this article API Key Management Article
• Configure SCIM - Access to the user guide can be found here Managing users via the SCIM API User Guide

HOW DOES THE SCIM API WORK?

With the SCIM API you can:

• Create new User records and corresponding Person Register records. 
• Update existing User records and corresponding Person Register records. 
• Deactivate Users (make them ‘Not Current’).
• Reactivate Users (make them ‘Current’).
• Create and Delete Assure Roles.
• Add and Remove Assure Roles from Users. 

Note: When an Assure role is created through SCIM, all permissions are set to Deny by default. A user with the appropriate permissions can then manually adjust the role’s permissions as needed. 

PREREQUISITES

Before enabling SCIM, you must have:

• Person/User connection enabled in Assure, because we are creating Person Register records alongside the user records.
• OKTA or ENTRA as your Identity Provider.
• SSO-only login enabled (for both Assure and AssureGO+).
• User API and User Data Import disabled (Any data imports configured previously will be automatically disabled)
• External IDs for Organisational Units. Please note, Organisational Units can still exist in Assure without External IDs, however SCIM will only recognise those with External IDs. 

Some settings are only visible to Evotix privileged accounts. Please contact Evotix Support or your Customer Success Manager to ensure all prerequisites are in place.

MINIMUM REQUIRED FIELDS

Each user record created or updated through SCIM must include:

• Org Unit (SCIM Enterprise schema department)
• Forename (First Name)
• Surname (Last Name)
• Email 

Defaults:

• If User Access Type is not provided, users will be given an Assure & AssureGO+ License, provided there are enough licenses available. 
• If User Specific Time Zone, Language, and Date Format are not provided, defaults from system settings will apply. 

IMPACT ON RECORDS IN ASSURE 

When managing User and Person Register records via the SCIM API, some fields cannot be updated outside of SCIM. These fields are read only in the User Interface of Assure, and are as follows: 

Note: 

1. Roles cannot be manually added or removed from a user, but the org unit and option to include children can be edited for each role. 

2. User Specific Time Zone, Language, and Date Format can be manually amended by the user themselves following the steps here. If the user is then updated via the SCIM API, these fields will reset to reflect the update.  

Note: 

1. Person Register records can still be created and edited freely in Assure if they are not linked to a user record. 

2. When a user is made not current, their associated Person Register record will be automatically unlinked from the User and the fields become editable. If the user is ever reactivated, then the person register record will be relinked and the fields will return to being read only.

EXCEPTIONS

SCIM requests will fail, and manual intervention will be required in Assure if: 

• The change would exceed the number of available licenses in your Assure system. 
• A duplicate email or username exists. 
• You try to deactivate a user who has an Insights Designer license and owns insights dashboards. Dashboards must be reassigned before the user can be deactivated. Steps to do so can be found here.  

OUT OF SCOPE

The SCIM API does not manage:

• Masked Parent – This must be applied manually to each individual user profile as required.
• Supervisor Privileges – When SCIM is enabled, Evotix will configure a default supervisor privilege to apply to all newly created users. You can apply specific permissions to this supervisor privilege by following the steps detailed here. It cannot be deleted, however the permissions within it can be amended at any time. Supervisor Privilege can also be set manually per user. 
• Insights Licenses – All newly created users will be given an Insights viewer license by default; if the number of licenses is exceeded, it will be set to none. Insights license can also be set manually per user.
• Different Org Units for different Assure Roles – A user can have multiple roles assigned to them via SCIM. By default, the org unit for those roles will reflect the Default Unit of the user and will include children. This can be manually amended in Assure but will reset if the user’s default org unit is updated. 
• Updates to Notifications, Notification Groups, Default Org Unit/Master Settings, User Selections in System Settings, and Workflow Rules – User connections must be amended manually. 
• Default Values in Caption Maintenance - Any default values set within the Person Register caption maintenance area are not taken into consideration by the API.
• Mandatory Fields - Where a field has been set as mandatory for a Person Register record, this will be taken into consideration and must have a value within the SCIM call, or the record will not be created, which can cause synchronization issues.
• Deleting a user - Users can only be deactivated (i.e. made not current) via the SCIM API.

NEED HELP?

Please contact the Evotix Support team should you require additional support with the SCIM API.