Skip to main content

SCIM

In the case you are using your OpenID as the authentication method, you can use the SCIM protocol to manage your users

You can find the document on how to use the api in the SCIM documentation

Here is the standard response format (except for the service configuration endpoint):

{
  "totalResults": int,  // total number of object (all pages)
  "itemsPerPage": int,  // number of object in this page (Resources.length)
  "startIndex": int,    // the start index of this page
  "schemas": string[],  // the schema of this object (always "urn:ietf:params:scim:api:messages:2.0:ListResponse")
  "Resources": object[] // list of object in this response
}

SCIM discovery methods​

Here is a list of the service discovery method for the SCIM protocol, you will find the server configuration and implemented operation.

As well as the endpoint enabling you to discover the resources (endpoint) and schema (Field description for the objects) that are implemented.

Those endpoint can be called without being identified on the webservice (no session nedeed)

Service provider configuration​

Return the features of the SCIM protocole supported by Retail Ops

Method​

GET/api/externals/v1/scim/v2/ServiceProviderConfig

Arguments​

(none)

Body​

(none)

Response​

The SCIM configuration and supported options

Here is the documentation of the returned format:
RFC 7643 - 5. Service Provider Configuration Schema

example of response:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
  ],
  "documentationUri": "http://retail-operations-doc.enterprise.by.me/docs/SMOL-OC/",
  "patch": {
    "supported": false // Patch operation are not supported
  },
  "bulk": {
    "supported": false, // Bulk operation are not supported
    "maxOperations": 0,
    "maxPayloadSize": 0
  },
  "filter": {
    "supported": false, // Filter operation are not supported
    "maxResults": 0
  },
  "changePassword": {
    "supported": false  // Password cannot be change as they are handled by the openid
  },
  "sort": {
    "supported": false  // Not sort is supported, the users will be sorted by id ascending
  },
  "etag": {
    "supported": true
  },
  "authenticationSchemes": [  // The authentication is the same as the other endpoint of the api
    {
      "type": "customheader",
      "name": "Custom Header X-PHP-SESSID",
      "description": "Pass your external api session in the X-PHP-SESSID header, like our other api",
      "documentationUri": "http://retail-operations-doc.enterprise.by.me/docs/SMOL-OC/api/usage/"
    }
  ],
  "pagination": {
    "cursor": false,
    "index": true,  // we only support index based pagination
    "defaultPaginationMethod": "index",
    "defaultPageSize": 10,
    "maxPageSize": 50
  }
}

Schemas​

Returns the list and detail information on the schema (defined field in object models and constraint on those fields) defined and used by retail Ops

Method​

GET/api/externals/v1/scim/v2/Schemas

Arguments​

(none)

Body​

(none)

Response​

Here is the documentation of the returned format:
RFC 7643 - 7. Schema Definition

{
  "totalResults": int,  
  "itemsPerPage": int,
  "startIndex": int,
  "schemas": string[],
  "Resources": [
    {                             // schema definition
      "name": string,             // name of the schema
      "description": string,      
      "attributes": [
        {                         // Attribute definition
          "name": string,
          "type": string,
          "description": string,
          "multiValued": bool,    // if the value must conform to a predefined list
          "required": bool,
          "mutability": string,
          "returned": string,
          "uniqueness": string,
          "caseExact": bool,
          "canonicalValues": string[],  // if multiValued, contains the list of allowed values
          "subAttributes": Attribute[]
        }
      ],
      "schemas": string[],
      "id": string,
      "meta": {
        "resourceType": string,
        "created": string, // ex: "2025-05-05T06:22:16.661Z"
        "lastModified": string, // ex: "2025-05-05T06:22:16.661Z"
        "location": string,
        "version": string
      }
    }
  ]
}

Resource Types​

Returns the list and detail information of the implemented endpoints and supported schema for them

Method​

GET/api/externals/v1/scim/v2/ResourceTypes

Arguments​

(none)

Body​

(none)

Response​

Here is the documentation of the returned format:
RFC 7643 - 6. ResourceType Schema

{
  "totalResults": int,  
  "itemsPerPage": int,
  "startIndex": int,
  "schemas": string[],
  "Resources": [
    {                         // endpoint definition
      "name": string,
      "description": string,
      "endpoint": string,     // entrypoint url
      "schema": string,       // primary type schema of the resource in the response
      "schemaExtensions": [   // list of schema extension supported or required by the endpoint 
        {
          "schema": string,
          "required": true
        }
      ],
      "schemas": string[],
      "id": string,
      "meta": {
        "resourceType": string,
        "created": string, // ex: "2025-05-05T06:22:16.661Z"
        "lastModified": string, // ex: "2025-05-05T06:22:16.661Z"
        "location": string,
        "version": string
      }
    }
  ]
}

Resource Types​

Returns detail information of the implemented endpoints and supported schema for them by a resource id

Method​

GET/api/externals/v1/scim/v2/ResourceTypes/{id}

Arguments​

id id of the resource

Body​

(none)

Response​

Same as Resource Types Response

SCIM user methods​

Search known users

Method​

POST/api/externals/v1/scim/v2/Users/.search/
warning

Do not forget to add the / at the end of the url

Arguments​

(none)

Body​

{
  "schemas": string[],
  "startIndex": long,
  "count": long
}

Response​

RFC 7644 3.4.3 Querying Resources Using HTTP POST

json properties

{
  "totalResults": int,
  "itemsPerPage": int,
  "startIndex": int,
  "schemas": string[],
  "Resources": [
    {
      "schemas": string[],
      "id": string,
      "externalId": string,
      "meta": {
        "resourceType": string, // "User"
        "created": string,  // ex: "2025-05-05T06:22:16.661Z"
        "lastModified": string,  // ex: "2025-05-05T06:22:16.661Z"
        "location": string,
        "version": string
      },
      "name": {
        "honorificPrefix": string, // Title
        "givenName": string, // First name
        "familyName": string // Last name
      },
      "userName": string, // SSO user name
      "emails": [
        {
          "value": string, // Email
          "type": string, // "Work"
          "primary": bool // "true"
        }
      ],
      "preferredLanguage": string, // Preferred ISO code language
      "active": bool, // true if the user is active
      "retailOps": { // Retail ops informations 
        "role": string, // User role
        "profile": string, // User profile
        "openIDUserID": string, // 
        "domain": string, // Retail ops domain
        "sendInviteLink": bool, // true if a working mail is not defined
        "isLinkToAllStores": bool, // The user is linked to all stores
        "storeCodeList": [ // List of user store codes
          string
        ]
      },
    }
  ]
}

Get​

Returns details informations of a known user by his id

Method​

GET/api/externals/v1/scim/v2/Users/{id}

Arguments​

id (string): id of the user

Body​

(none)

Response​

RFC 7644 3.4.1 Retrieving a Known Resource

json properties

{
  "schemas": string[],
  "id": string,
  "externalId": string,
  "meta": {
    "resourceType": string, 
    "created": string,  // ex: "2025-05-05T06:22:16.661Z"
    "lastModified": string,  // ex: "2025-05-05T06:22:16.661Z"
    "location": string,
    "version": string
  },
  "name": {
    "honorificPrefix": string, // Title
    "givenName": string, // First name
    "familyName": string // Last name
  },
  "userName": string, // SSO user name
  "emails": [ // Emails of the user
    {
      "value": string,
      "type": string,
      "primary": bool
    }
  ],
  "preferredLanguage": string, // Preferred ISO code language
  "active": bool, // true if the user is active
  "retailOps": { // Retail ops informations 
    "role": string,
    "profile": string,
    "openIDUserID": string,
    "domain": string, // Retail ops domain
    "sendInviteLink": bool,
    "isLinkToAllStores": bool, // true if the user is linked to all stores
    "storeCodeList": string[] // List of user store codes
  },
}

Create​

Create a user

Method​

POST/api/externals/v1/scim/v2/Users

Arguments​

(none)

Body​

json properties

{
  "schemas": string[],
  "externalId": string,
  "name": {
    "honorificPrefix": string,
    "givenName": string,
    "familyName": string
  },
  "userName": string,
  "emails": [ // Emails of the user
    {
      "value": string,
      "type": string,
      "primary": bool,
    }
  ],
  "preferredLanguage": string,
  "active": bool,
  "retailOps": {
    "role": string, // User role
    "profile": string,  // User profile
    "openIDUserID": string, 
    "domain": string, // Retail ops domain
    "isLinkToAllStores": bool, // true if the user is linked to all stores
    "storeCodeList": string[]  // List of user store codes
  },
}

Response​

RFC 7644 3.3 Creating Resources

json properties

{
  "schemas": string[],
  "id": string,
  "externalId": string,
  "meta": {
    "resourceType": string, // "User"
    "created": string,  // ex: "2025-05-05T06:22:16.661Z"
    "lastModified": string,  // ex: "2025-05-05T06:22:16.661Z"
    "location": string,
    "version": string
  },
  "name": {
    "honorificPrefix": string, // Title
    "givenName": string, // First name
    "familyName": string // Last name
  },
  "userName": string, // SSO user name
  "emails": [
    {
      "value": string, // Email
      "type": string, // "Work"
      "primary": bool // "true"
    }
  ],
  "preferredLanguage": string, // Preferred ISO code language
  "active": bool, // true if the user is active
  "retailOps": { // Retail ops informations
    "role": string, // User role
    "profile": string, // User profile
    "openIDUserID": string, // 
    "domain": string, // Retail ops domain
    "sendInviteLink": bool, // true if a working mail is not defined
    "isLinkToAllStores": bool, // The user is linked to all stores
    "storeCodeList": string[] // List of user store codes
  },
}

Update​

Update the specific information of a known user

Method​

PUT/api/externals/v1/scim/v2/Users/{id}

Arguments​

id (string): id of the user

Body​

json properties

{
  "schemas": string[],
  "externalId": string,
  "name": {
    "honorificPrefix": string,
    "givenName": string,
    "familyName": string
  },
  "userName": string,
  "emails": [ // Emails of the user
    {
      "value": string,
      "type": string,
      "primary": bool,
    }
  ],
  "preferredLanguage": string, -------
  "active": bool, // -------------
  "retailOps": {
    "role": string, // User role --------
    "profile": string,  // User profile ----------
    "openIDUserID": string, // ---------
    "domain": string, // Retail ops domain
    "isLinkToAllStores": bool, // true if the user is linked to all stores ----------------
    "storeCodeList": string[]  // List of user store codes --------------
  },
}

Response​

RFC 7644 3.5.1 Replacing with PUT

json properties

{
  "schemas": string[],
  "id": string,
  "externalId": string,
  "meta": {
    "resourceType": string, // "User"
    "created": string,  // ex: "2025-05-05T06:22:16.661Z"
    "lastModified": string,  // ex: "2025-05-05T06:22:16.661Z"
    "location": string,
    "version": string
  },
  "name": {
    "honorificPrefix": string, // Title
    "givenName": string, // First name
    "familyName": string // Last name
  },
  "userName": string, // SSO user name
  "emails": [
    {
      "value": string, // Email
      "type": string, // "Work"
      "primary": bool // "true"
    }
  ],
  "preferredLanguage": string, // Preferred ISO code language
  "active": bool, // true if the user is active
  "retailOps": { // Retail ops informations 
    "role": string, // User role
    "profile": string, // User profile
    "openIDUserID": string, // 
    "domain": string, // Retail ops domain
    "sendInviteLink": bool, // true if a working mail is not defined
    "isLinkToAllStores": bool, // The user is linked to all stores
    "storeCodeList": string[] // List of user store codes
  },
}

Errors​

When a standard scim error is returned it follows the following format:

RFC 7644 3.12 HTTP Status and Error Response Handling

{
  "schemas": string[],
  "detail": string,    // detail of the error
  "scimType": string,  // standard scim type of the error if exist
  "status": string,    // http status code  ex: 402, 403, 404, ....
}