This article explains how to use the Assure SCIM API (System for Cross-domain Identity Management -- a secure RESTful API that automates the management of User records and Person Register records in Assure) to provision, update, deactivate, and reactivate users, and to manage Assure Roles. The SCIM API integrates with OKTA or Microsoft Entra ID as the Identity Provider and requires SSO-only login to be enabled. This is not a self-service configuration; the API functionality must be enabled by the Evotix Support Team before use, and implementation typically requires technical expertise from the organisation's IT function.
Cross-module scope: This article spans Assure User Management, the Person Register (within the People and Training module), Role Permissions, and Insights+. A companion article -- the Assure SCIM Customer Set Up Guide -- covers the technical setup steps for connecting OKTA or Microsoft Entra ID to Assure using the SCIM 2.0 protocol.
Prerequisites
Before enabling SCIM, confirm all of the following are in place:
- Person/User connection enabled in Assure, because Person Register records are created alongside user records.
- OKTA or Microsoft Entra ID 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 -- Organisational Units can still exist in Assure without External IDs, however SCIM will only recognise those with External IDs.
Note: Some settings are only visible to Evotix privileged accounts. Contact Evotix Support or your Customer Success Manager to ensure all prerequisites are in place.
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
To get started with the SCIM API, complete the following three steps in order:
- Request Access -- Contact your Customer Development Manager (CDM) or Customer Success Manager (CSM) to request that the SCIM API is enabled on your Assure instance.
- Generate API Keys -- You can create and manage your API authentication keys at any time in Assure. Refer to the API Key Management Article for full instructions.
- Configure SCIM -- Access the dedicated Managing users via the SCIM API User Guide for full technical configuration instructions. The companion article Assure SCIM Customer Set Up Guide covers the setup steps for connecting OKTA or Microsoft Entra ID to Assure using SCIM 2.0.
What the SCIM API Can Do
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.
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)
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 Assure user interface.
User Record - Read-Only Fields
The following fields on a User Record become read-only in the Assure UI when SCIM is active:
| User Record Read Only Fields |
| Username |
| Full Name |
| Linked Person Record |
| User Access Type |
| Is Current User |
| Default Unit |
| Is Manager |
| Manager |
| User Specific Time Zone |
| Language |
| Date Format |
| Role (Add, Remove) |
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.
Person Register Record - Read-Only Fields
The following fields on a Person Register record become read-only in the Assure UI when the record is linked to a SCIM-managed user:
| Person Register Record Read Only Fields |
| Org Unit |
| Reference |
| Linked User License |
| Current? |
| Title |
| Forename(s) |
| Surname |
| Job Title |
| Occupation |
| Manager Name |
| Address Line 1 |
| Address Line 2 |
| Address Line 3 |
| Town |
| County |
| Postcode |
| Phone |
| Mobile |
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 licences in your Assure system.
- A duplicate email or username exists.
- You try to deactivate a user who has an Insights Designer licence 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?
Contact the Evotix Support Team if you require additional support with the SCIM API.
AI Metadata
Product Area: Assure -- User Management, Person Register (People and Training module), Role Permissions, Insights+, System Configuration
User Role: Assure Administrator (to raise the request and configure permissions); IT Administrator (to implement the API); Evotix Support Team (to enable the API)
Tags: SCIM API, user provisioning, user deprovisioning, Person Register, Assure Roles, OKTA, Microsoft Entra ID, SSO, Identity Provider, User Management, read-only fields, not current, deactivate user, reactivate user, Insights Designer, Supervisor Privileges
Version/Region: All Assure versions; all regions
Important synonyms:
- SCIM API = System for Cross-domain Identity Management API = SCIM integration
- Deactivate = Make not current = deprovision
- Reactivate = Make current = reprovision
- Person Register = People Register = Person Record
- Org Unit = Organisational Unit
- CDM = Customer Development Manager
- CSM = Customer Success Manager
- OKTA = Okta Identity Provider
- Microsoft Entra ID = Entra ID = Azure AD (legacy name)
- Insights+ = Insights Plus = Insights Designer licence
Suggested embedding keywords: SCIM API Assure, manage users SCIM, automate user provisioning Assure, OKTA Assure integration, Entra ID Assure SCIM, deactivate user SCIM, Person Register SCIM read-only fields, SCIM prerequisites Assure, SCIM not current user, SCIM Assure roles, SCIM out of scope, Assure SCIM API setup
Relevant modules and cross-module implications: This article spans Assure User Management and the Person Register module (People and Training area). When SCIM is enabled, many User Record and Person Register fields become read-only in the Assure UI and can only be updated via SCIM. Role Permissions are affected: Roles can be created, deleted, and assigned/removed via SCIM, but all permissions default to Deny on creation and must be configured manually. Insights+ licences are assigned by default but are not managed by SCIM. Supervisor Privileges are partially handled via a default Supervisor Privilege created by Evotix at setup time. Notifications, Notification Groups, Workflow Rules, and Caption Maintenance default values are outside the scope of SCIM and must be managed manually in Assure. A companion article -- the Assure SCIM Customer Set Up Guide -- covers the OKTA and Microsoft Entra ID technical configuration steps.