Licenses

The Licenses API allows you to check, activate, or return SmartServer Licenses.  A Device capacity license is needed to access external devices. If the SmartServer is only used for RNI or IP-852 routing then a device capacity license is not needed. The maintenance license allows you to upgrade this SmartServer software at a later date or contact the support team. The maintenance license device count should match the device capacity device count.  The SmartServer supports both Online and Offline Activations. That is, if the SmartServer has internet access and can access the License server, then you can use online activation.  If the SmartServer has no internet access or cannot access the license server, then you need to use offline activation.  Only online License returns are currently supported, offline license returns are not supported. 

License information is requested with a REST API request, but the license information may show up in the REST request response or in a WebSocket update.

The license status request /iap/lic/status provides the current state of the licenses on the SmartServer.  You can get all the current licenses using the /iap/lic request.

Online Activations (SmartServer can access license server):

  1. To download available licenses from the cloud, you must have previously specified the licenses' customer ID with the /iap/lic/accounts?segmnetId={segmentId} request or use the CMS Web page.
  2. Use the /iap/lic/cloud request to download all available licenses for this customer ID.  The license information shows up as a WebSocket update UPD:LIC:CLOUD
  3. Use the /iap/lic/cloud/download request to activate a one or more licenses.
  4. You can return all the licenses to the cloud using the /iap/lic/cloud/upload request.  
    Note:  Returning all licenses means that you can no longer access internal or external devices or use built-in features like scheduler or data logging. 

Offline Activations (SmartServer can't access license server):

Offline activation requires you to get an offline activation file (no file extension on the file). Once you have the offline license file you can use the /iap/lic/activation request to activate the license. Currently there is no way to return or revoke the licenses while offline.


URI Definition

Method

URI and Fields

GET


/iap/lic

List current licenses.

Parameters

For information on specifying query parameters, see Queries and Parameters.

Example

GET https://10.0.0.78/iap/lic?pg=1&sz=25

RESPONSE

[
    {
      "scName":"SmartServer IoT",
      "description":"50-device capacity",
      "status":"Active",
      "activationDate":"2022-02-18",
      "licenseId":"776541e6-64f1-4593-a835-55136c9d1062"
    }

]                                                                                                                                                          

  

/iap/lic/count

Number of current licenses.

Parameters

For information on specifying query parameters, see Queries and Parameters.

Example

GET https://10.0.0.78/iap/lic/count
RESPONSE
{
    "value":1
}                                                                                                                                                          

  

/iap/lic/status

License status.   

Parameters

For information on specifying query parameters, see Queries and Parameters.

Example

GET https://10.0.0.78/iap/lic/status

RESPONSE
[
    {
      "scName":"SmartServer IoT",
      "totalCapacity":100,
      "usedCapacity":1,
      "expirationDate":"2023-03-14",
      "status":"LICENSED",
      "installCode":"17qam77",
      "licensingId":null,
      "segmentId":1
    }

]                                                                                                                                                          

  

PUT


/iap/lic/accounts

Enter Customer ID.

Query Parameter

Argument             

Description                                                                                                  

segmentId

Used to enter the SmartServer Licenses Customer ID

The licenses Customer ID is required to download the available licenses from the cloud.

You can get the Segment ID from the /iap/lic/status response using the following request/payload:

   Request:   /iap/lic/accounts?segmnetId={segmentId}

   Payload:   {Licenses customer ID}


For information on specifying query parameters, see Queries and Parameters.

Example

https://10.0.0.229/iap/lic/accounts?segmnetId=1


PAYLOAD
893210a7-f0f0-f0f0-f0f0-767abf001234

                                                                                                                                                          

  

POST/iap/lic/cloud

Download license from cloud (online only)

Parameters

For information on specifying query parameters, see Queries and Parameters.

Example

GET https://10.0.0.78/iap/lic/cloud

RESPONSE: HTTP 204 - success but no response data

WEBSOCKET (WS) UPDATE
{
    "action":"UPD:LIC:CLOUD",
    "payload":
      [
        {
          "licensingId":"893210a7-f0f0-f0f0-f0f0-767abf001234",
          "description":"1000-device capacity",
          "licenseId":"893210a7-f0f0-f0f0-f0f0-767abf001234",
          "transferDate":"2022-01-20"
        },
        {
          "licensingId":"bf6f94f8-fdfd-fdfd-fdfd-ec78ba075678",
          "description":"1-year maintenance",
          "licenseId":"bf6f94f8-fdfd-fdfd-fdfd-ec78ba075678",
          "transferDate":"2022-01-24"
        }
    ]
}                                                                                                                                                          

  

/iap/lic/cloud/download

Activate License (online only)

Query Parameter

Argument             

Description                                                                                                  

scName

Segment controller name

For information on specifying query parameters, see Queries and Parameters.

Example

POST https://10.0.0.229/iap/lic/cloud/download?scName=SmartServer IoT

Payload
[
    "16c91c71-6b61-4666-af84-7585aebe1234",
    "bf6f94f8-6fd5-44e0-a1b1-ec78ba075678"
]

RESPONSE                                                                                                                                                         

  Note: it can take up to a minute for the SmartServer to process this request before you will see the updated information in the /iap/lic/status or /iap/lic request

/iap/lic/cloud/upload

Return or revoke license to cloud (online only)

Parameters

For information on specifying query parameters, see Queries and Parameters.

Example

POST https://10.0.0.229/iap/lic/cloud/upload

PAYLOAD:
{
    "include":[]
}

RESPONSE HTTP 200
[
    "16c91c71-f0f0-f0f0-f0f0-7585aebe1234",
    "bf6f94f8-f0f0-f0f0-f0f0-ec78ba075678"


WEBSOCKET (WS) UPDATES (you may see two updates for each license)   

{"action":"DEL:LIC","payload":{"scName":"SmartServer IoT","description":"50-device capacity","status":"Active","activationDate":"2022-03-14","licenseId":"16c91c71-6b61-4666-af84-7585aebe1234"}}
{"action":"DEL:LIC","payload":{"scName":"SmartServer IoT","description":"1-year maintenance","status":"Expiring 2023-03-14","activationDate":"2022-03-14","licenseId":"16c91c71-6b61-4666-af84-7585aebe1234"}}

{"action":"NTF:LIC:ACTION","payload":{"type":"REVOKE","sid":"17qehie","scName":"SmartServer IoT","licenseId":"d094cdd3-f0f0-f0f0-f0f0-8470dfd2bfb0","licensingId":"d094cdd3-f0f0-f0f0-f0f0-8470dfd2bfb0","error":{"name":"none","desc":"No errors."}}}
{"action":"NTF:LIC:ACTION","payload":{"type":"REVOKE","sid":"17qehie","scName":"SmartServer IoT","licenseId":"bf6f94f8-f0f0-f0f0-f0f0-ec78ba075678","licensingId":"bf6f94f8-f0f0-f0f0-f0f0-ec78ba075678","error":{"name":"none","desc":"No errors."}}}                                                                                                                                                    

  Note: it can take up to a minute for the SmartServer to process this request before you will see the updated information in the /iap/lic/status or /iap/lic request

/iap/lic/activation

Offline Activation  (offline only)

Parameters

For information on specifying query parameters, see Queries and Parameters.

Payload format

-----------------------------4291847375880236859505230591
Content-Disposition: form-data; name="licenseFile"; filename="lservrc_50_devicecap_78"
Content-Type: application/octet-stream

<file data>

-----------------------------4291847375880236859505230591--
                                                                                                                                                

 Note: For the payload data the line terminator is <cr><lf> and is used after boundary strings, after header information, before the file contents and after the file contents.

Response Codes


Status CodeDescription
204Indicates that the request was successfully sent.
400Indicates an invalid request.
415Indicates that the Content-Type header needs to be multi-part/form-data. Other values can also return a 415 status code.

Examples

HTTPS header must use Content-Type of  multipart/form-data.  Adding the boundary string is optional.

.

https://10.0.0.78/iap/lic/activation


PAYLOAD
-----------------------------4291847375880236859505230591
Content-Disposition: form-data; name="licenseFile"; filename="lservrc_50_devicecap_78"
Content-Type: application/octet-stream

*L ERtOg/dxok2ZnYFp/oQOO1f5q7gNbZDVmsulRpB1hW8SJpTRNr/fe+EisokXRbOcoodcPHsUNLYZYkgcDY8E23m/jE3GUWx0USub4Ld+ttt5sO4l3lW8RHZreTrmG+OZZwt+OB/RZ3+
rcisBQl1HSu4j4shoqjR9I6iRmcSJKcmMFtK17jB+kkgJDsbQKRly/nNKwGmU/DV9Nr+73PGEp94bCM0pR6yZzCjUEXktZTm2PBtLOLhKQaIaCndKCOCD3W0HpCXSI2XQVBuwTaNRps
F9/8tdgrHg/3oFfBgMe9n6/bLQ1dsNHshEZ4gqw5Ht2rK571xM+D/dpjV2Rus7N2IhZ8LYIbOjC8oF6adZLaXKPcJdyLl3G/mpGKykW27eKMVRrUTFvR9rbuZsdOTx4ydlcK8V9ZQa7ZVfFkD
YSCiTwg+bGlq+A9Icq18gO24rwEJ6+/AwdGxgrq4Ll9ncutqYqkpjoUWYoFVG9DqX8469rhIFvI3B5n9hI7TC45LofLUXYiQj1nQPFqNGdo1c8epZQlLBmO6N6fgCWRv846D/UWOG5eC7ydq
MV9abiRvkBQRSQ0IyC4MJBQRSQ0IyBgEBBwEBBCU4YjFiNmYxZC0zNzY5LTRmNGUtYjM4Ny0zNGUzMmVlOTYzYmQACAEBCUD69pj3TGyP3iXkjDW3v9YvqF8/IzRjnNPH5Iw3ste7
vvIxac40qv8U46e1vA2IWHLX0S4wCDZhm4lh55efpLXVCoIOMIIBCgKCAQEA0eFLVv7GfQleQwsoKgf+Cta0DJrI6MkMThmP80QtzDgtRZycCwqKaaeCH1aB0I8HMjSVKX30Ra2BosNkvN
3cA+6iKAnduOS7p14azlMr1P/CQo99NNSj4xZGJomZvCP+Oj1Z0uIw8lUko9anX426C0pVk3QxqGZSHaKg4DtuxA2tsjHFdHacgdKqbH7wuJiNLHnak2hFqm2HkLTU/OP3hAI0+qSfQcV+P3
xJoP+qQRcS0Dosss0xZiLWb9/3B652t0ZXwR1NyGneqlGNI7O3DduJ23A74mpXVXIWkkc9CKAYGWVzi7ktgl2NbFYBMtXYpzKhaojetoKVNR9pf55T+wIDAQABBCU4YjFiNmYxZC0zNzY5L
TRmNGUtYjM4Ny0zNGUzMmVlOTYzYmQABwEBDIIAk/tosXXqq1mPtOlBwYvp3/Bck9d6SHbpR1tiodP0zhvrolWC6ccTf9CnhNAPC9FsmhBij7ZyRz2XR/vq6VbgaC0xPkZ01JLkQJeMjEhK
RTBgifqi1u4i+yRmSMlsrOvYewe5C01DKkAbzKcoCjcYgGas+o4juLCcPKhqydqF3sFvFwAdYWqdQgyZ9KAg0uNoJOShSIa2tYd5ONQ+dStA5oSGYwmk9FoswVTEAGrc+mcM4P6bUNEGK
XTl2ihUQuZiRdxpomQnsYoAMlGzRfK7h7zf5vWz6+UYUa7ByM7ii4UOwto3XD9kyyF0B86fHgOJ0vxwHdxHBgC6myCJjIRndwAAAr8=# "Capacity" version "", no expiration date, aggregate##
AID=d03a0bf3-352d-4e80-9ad9-be0c8e94b547

-----------------------------4291847375880236859505230591--


RESPONSE
{"value":true} 


WEBSOCKET (WS) UPDATES       

One WS ACTION update   
{"action":"NTF:LIC:ACTION","payload":{"type":"SET","sid":"17qam77","scName":"SmartServer IoT","licenseId":null,"licensingId":null,"error":{"name":"none","desc":"No errors."}}}   

One WS update for each license
{"action":"UPD:LIC","payload":{"scName":"SmartServer IoT","description":"50-device capacity","status":"Active","activationDate":"2022-03-15","licenseId":"f842530b-a930-43c5-b095-c3d66db08b80"}}


One WS total update
{"action":"UPD:LIC:TOTAL","payload":{"scName":"SmartServer IoT","totalCapacity":250,"usedCapacity":1,"expirationDate":"2023-03-15","status":"LICENSED","installCode":"17qam77","licensingId":null,"segmentId":1}}

Note: Response of value:true means format of the payload is correct. In a later process the payload data is checked and if a valid license file then the license will get activated

EXAMPLE Web Page source code

Offline License Activation source code
<html>
	<body>
		<input type="file" id="licenseImportFile" name="myfile" onchange="SendImportFile()">
	<body>
	<script>
		function SendImportFile() {
  			var formData = new FormData(); 
  			var fileObj = document.getElementById("LicenseImportFile").files[0];
  			var xhr = new XMLHttpRequest();
  
			xhr.onreadystatechange = function() {
			if (xhr.readyState == 4 && xhr.status == 204) {
				// Write successful
			}
			else if(xhr.readyState == 4 && xhr.status == 401)
			{
				//login();
			}
			else if(xhr.readyState == 4) {
				//error
			}

  			xhr.open("POST", "https://10.0.0.229/iap/lic/activation", true);
  			formData.append("licenseFile", fileObj, fileObj.name);
  			xhr.send(formData);
  		}		
</script>
</html>