###########################
Appendix G - RLM Cloud API
###########################

RLM Cloud is most effectively used with it's GUI at https://rlmcloud.com/manage, however some
of our customers will want to be able to automatically load their customer data and provision
license servers directly from their internal CRM system.

RLM Cloud supports Web Services to control most aspects of the RLM Cloud database and license
servers. The API is implemented as a simple REST-style service, using JSON to encode the
information going to and from the RLM Cloud system. While this API does not provide 100% of
the capability of the GUI, it will allow you to do all the basic operations from your CRM system.
In some cases, you will need to do some generic setup prior to using the API.

The RLM Cloud API is described at: 'https://rlmcloud.com/api/api.php#'

.. note:: The RLM Cloud API will soon be migrated to this document.

----

*************
ID Licensing
*************

Documentation for RLM Cloud’s ID Licensing endpoints.

RLM CLoud’s ID Licensing API is now SCIM v2 compliant - The Users and Groups endpoints return SCIM 
formatted responses and may now be integrated with Microsoft Azure Entra ID. See 
:ref:`scim-provisioning` below.

Current Location: https://www.rlmcloud.com/id-api/

.. warning:: Users and Groups endpoints require the new RLM Cloud Bearer Token authorization. 
   Token provided to ISV upon request.

Assign and Unassign endpoints require the standard RLM Cloud Authorization variables in the header 
of the body:

.. code-block:: html
   
   {
    "header":
    {
        "user":"test",
        "password":"098f6bcd4621d373cade4e832627b4f6"
    }
   }

----

SSO Login POST
==============

Get the CUSTOMER lines associated to a user.

.. code-block:: html

	POST /id-api/login.php HTTP/1.1
	Host: www.rlmcloud.com

	{
		"isvname":"demo",
		"username":"someone@isv.com",
		"password":"4766221402bb5c85c50d99db125cd789d38c4a09a758493fa606e1ef8ee5184c"
	}

----

SSO Users GET
=============

Get all current SSO Users.

.. code-block:: html

	GET /id-api/Users.php HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Groups GET
==============

Get all current SSO Groups.

.. code-block:: html

	GET /id-api/Groups HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Users GET User by ID
========================

Get a specific SSO User by ID.

.. code-block:: html

	GET /id-api/Users/35 HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Groups GET Group by ID
============================

Get a specific SSO Group by ID.

.. code-block:: html

	GET /id-api/Groups/39 HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Users GET Search
=====================

Search for a specific SSO User. The filter applies to the user’s email address value.

.. code-block:: html

	GET /id-api/Users?filter=userName+eq+"test@test.com" HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Groups GET Search
=====================

Search for a specific SSO Group. The filter applies to the group’s name value.

.. code-block:: html

	GET /id-api/Groups?filter=displayName eq "Reprise" HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Users PUT
==============

Update an SSO User. This method will replace and update all values associated to a user.

.. code-block:: html

	PUT /id-api/Users/35 HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "email": "nathanael.washington6@gmail.com",
	  "name": "Nathanael Washington",
	  "enabled": 1,
	  "company": "Reprise Software",
	  "title": "",
	  "phone": "3333333333"
	}

----

SSO Groups PUT
===============

Update an SSO Group. This method will replace and update all values associated to a group.

.. code-block:: html

	PUT /id-api/Groups/39 HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "name": "Reprise Software",
	  "members": [
	    { "value": "35" }
	  ],
	  "notes": "Reprise Software Group Updated"
	}

----

SSO Users DELETE
==================

Delete an SSO User from the database.

.. code-block:: html

	DELETE /id-api/Users/1 HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Groups DELETE
==================

Delete an SSO Group from the database.

.. code-block::

	DELETE /id-api/Groups/1 HTTP/1.1
	Host: www.rlmcloud.com

----

SSO Users POST
==============

Create an SSO User.

.. code-block:: html

	POST /id-api/Users HTTP/1.1
	Host: www.rlmcloud.com

	{
	    "email": "test@testing.com",
	    "name": "John Smith",
	    "company": "Reprise Software",
	    "title": "test",
	    "phone": "3032291026",
	    "enabled": 1,
	    "password": "testing"
	}

----

SSO Groups POST
================

Create an SSO Group.

.. code-block:: html

	POST /id-api/Groups HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "name": "QA Team",
	  "members": [
	    { "value": "49" }
	  ],
	  "notes": "Quality Assurance"
	}

----

SSO Assign POST
===============

Assign a user to a server.

.. code-block:: html

	POST /id-api/Assign HTTP/1.1
	Host: www.rlmcloud.com

	{
	    "header":
	    {
	        "user":"test",
	        "password":"test"
	    },
	    "data":
	    {
	        "user_id": "35",
	        "server_id": "28469"
	    }
	}

----

SSO Unassign POST
=================

Remove a user from a server.

.. code-block:: html

	POST /id-api/Unassign HTTP/1.1
	Host: www.rlmcloud.com

	{
	    "header":
	    {
	        "user":"test",
	        "password":"test"
	    },
	    "data":
	    {
	        "user_id": "1",
	        "server_id": "1"
	    }
	}

----

.. _scim-provisioning:

******************
SCIM Provisioning
******************

SCIM patch operations format is required:

.. code-block:: text

	{
	“schemas”:[“urn:ietf:params:scim:api:messages:2.0:PatchOp”],
	“Operations”:[
	{
	“op”: “add|replace|remove”,
	“path”: “attribute”
	“value”: “”
	},
	…
	]
	}

SSO Users PATCH SCIM
====================

Update an SSO User. This method updates only the supplied fields for the SSO User. 

.. code-block:: html

	PATCH /id-api/Users/35 HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
	  "Operations": [
	    { "op": "replace", "path": "active", "value": true },
	    { "op": "replace", "path": "name.formatted", "value": "John Reprise" },
	    { "op": "replace", "path": "emails", "value": [ { "value": "John@example.com", "primary": true } ] },
	    { "op": "replace", "path": "phoneNumbers", "value": [ { "value": "+1-555-123-4567" } ] },
	    { "op": "replace", "path": "title", "value": "Lead Engineer" },
	    { "op": "replace", "path": "company", "value": "Reprise Software" },
	    { "op": "replace", "path": "notes", "value": "VIP customer" },
	    { "op": "add", "path": "active", "value": true },
	    { "op": "add", "path": "name.formatted", "value": "John Reprise" },
	    { "op": "add", "path": "emails", "value": [ { "value": "John@example.com", "primary": true } ] },
	    { "op": "add", "path": "phoneNumbers", "value": [ { "value": "+1-555-123-4567" } ] },
	    { "op": "add", "path": "title", "value": "Lead Engineer" },
	    { "op": "add", "path": "company", "value": "Reprise Software" },
	    { "op": "add", "path": "notes", "value": "VIP customer" },
	    { "op": "remove", "path": "name.formatted", "value": "" },
	    { "op": "remove", "path": "phoneNumbers", "value": [ { "value": "" } ] },
	    { "op": "remove", "path": "title", "value": "" },
	    { "op": "remove", "path": "company", "value": "" },
	    { "op": "remove", "path": "notes", "value": "" }
	  ]
	}

----

SSO Users PATCH SCIM Enable/Disable a User
==========================================

Example of enabling or disabling an ID Licensing user.

.. code-block:: html

	PATCH /id-api/Users/35 HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
	  "Operations": [
	    { "op": "replace", "path": "active", "value": true }
	  ]
	}

----

SSO Users PATCH SCIM Change User Password
==========================================

Example of updating the password of an ID Licensing user.

.. code-block:: html

	PATCH /id-api/Users/49 HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
	  "Operations": [
	    { "op": "replace", "path": "password", "value": "new_password" }
	  ]
	}

----

SSO Groups PATCH SCIM
=====================

Update an SSO Group. This method updates only the supplied fields for the SSO Group. 

.. code-block:: html

	PATCH /id-api/Groups/69 HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
	  "Operations": [
	    { "op": "add", "path": "members", "value": [{ "value": "49" }] },
	    { "op": "remove", "path": "members", "value": [{ "value": "49" }] },
	    { "op": "replace", "path": "members", "value": [{ "value": "49" }] },
	    { "op": "replace", "path": "active", "value": true }
	  ]
	}

----

SSO Groups PATCH SCIM Enable/Disable Group
==========================================

Example of enabling or disabling an ID Licensing group.

.. code-block:: html

	PATCH /id-api/Groups/69 HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
	  "Operations": [
	    { "op": "replace", "path": "active", "value": true }
	  ]
	}

----

SSO Users POST SCIM
===================

Create an SSO User.

.. code-block:: html

	POST /id-api/Users HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
	  "userName": "alice@example.com",
	  "name": { "formatted": "Alice Example" },
	  "emails": [{ "value": "alice@example.com", "primary": true }],
	  "phoneNumbers": [{ "value": "+1-555-1234" }],
	  "active": true,
	  "title": "Engineer"
	}

----

SSO Groups POST SCIM
====================

Create an SSO Group.

.. code-block:: html

	POST /id-api/Groups HTTP/1.1
	Host: www.rlmcloud.com

	{
	  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
	  "displayName": "Developers",
	  "externalId": "dev-group"
	}