SCIM
SCIM is a protocol designed to enable the synchronisation and provisioning of users between multiple system needing to know and authenticate users when using an unified user management.
It's defined by the IETF in 3 RFC:
The protocol will only work if Retail Ops is configured to use an OpenID as the authentication method.
See Retail Ops SSO.
You can find the entrypoint in the (SCIM API documentation).
Use cases
When using Retail Ops with an OpenID, the users must be defined ahead of time to be able to connect to Retail Ops (User management).
The standard way is to create the user in the administration panel then activate the user which send the user an email with an activation link.
The SCIM protocol gives you the possibility to manage user by the API using a standard protocol.
This permits you to have your OpenID identity provider as the central place where you manage your users and using this API you can push in RetailOps the user information (creation, deactivation, role, store assignation).
The API provides 2 ways to activate an user:
- Direct activation using the OpenID user ID
- Email link activation
Usage
User Activation
Deactivation
To deactivate a user you only need to update it with the field active at false.
Direct Activation
If you know the OpenID identifier of your user you can enable them directly using the api, without the need for your users to use an invite link.
To use the direct activation when creation or updating an user you need to pass 2 values:
| field | value |
|---|---|
active | true |
retailOps.openIDUserID | The ID of the user in your OpenID |
This is the only case when you are allowed to pass the active field with a value of true.
Activation using invite email
You can also use the standard process of user activation using the email with invitation link.
To do this you only need to set the retailOps.sendInviteLink to true.
When an invitation link is sent, the user is set in the pending invitation state until it use the link after which if pass to the active state.
Only the last invitation link is valid.
Store assignation
User can be assigned to all stores or a specific list of stores, you can only use one mode at a time.
To assign a user to all stores, set the field retailOps.isLinkToAllStores to true
Or if you want the user to be assigned to a list of stores fill the retailOps.storeCodeList field with the list of stores code you want your user to be assigned to.
API call format
Json properties
| Type | OnCreate | OnUpdate | Attribute | Comment |
|---|---|---|---|---|
| string[] | M | M | schemas | |
| string | F | F | id | |
| string | M | userName | ||
| string | M | name.honorificPrefix | The title | |
| string | M | name.givenName | The first name | |
| string | M | name.familyName | The last name | |
| string | M | preferredLanguage | ||
| string | M | emails[?].value | Emails of the user | |
| bool | G1 | G1 | active | Determine if the user is active or not |
| string | M | externalId | id of the user in the external system | |
| string | F | F | meta.resourceType | |
| dateTime | F | F | meta.created | Creation date (ex :"2025-05-05T06:22:16.661Z") |
| dateTime | F | F | meta.lastModified | Last modification date (ex :"2025-05-05T06:22:16.661Z") |
| string | M | retailOps.role | the retail ops role name | |
| string | M | F | retailOps.profile | [user|central] |
| string | G1 | G1 | retailOps.openIDUserID | if given to us we do not need to send the invite link |
| string | G1 | G1 | retailOps.domain | |
| bool | retailOps.sendInviteLink | If true will send an email invite | ||
| bool | M G2 | G2 | retailOps.isLinkToAllStores | |
| string[] | M G2 | G2 | retailOps.storeCodes |
M = Mandatory, G{N} = group (attribute that work in group), F = Forbidden
Group:
- If retailOps.openIDUserID is provided then : retailOps.domain is mandatory and active can be set
- See Store assignation
schemas
All the schemas which define the models of data in the request or the response.
id
It must be filled for "Get", "Search" and "Update", it must not be filled for "Creation".
preferredLanguage
It's the ISO code of the user language (ex: en-GB or fr-FR)
emails[?].value
Only the primary (email with type = "work" and primary = true) or, if not exists, the first email will be used
active
It can be set to true only if the retailOps.openIDUserID is provided.
See User activation
meta.resourceType
The value must be "User"
retailOps.role
One of the role in Retail Ops.
retailOps.profile
It has only two values, "user" and "central".
retailOps.openIDUserID
The user ID in OpenID.
See User activation
retailOps.domain
Used by Retail Ops to ensure that the openIDUserID is not already in use by another user on the same domain.
Pass the domain name used to open Retail Ops with your OpenID
retailOps.sendInviteLink
It takes true value if the openIDUserID is not given, and an Email is sent.
See User activation
retailOps.isLinkToAllStores
True if the user is linked to all the stores.
See Store Assignation
retailOps.storeCodes
If retailOps.isLinkToAllStores is false, it's the list of all the store code which the user is attached.
See Store Assignation