Introduction

Zentitle SaaS Licensing is implemented using REST webservices following the conventional paradigm based on the HTTP verbs Post, Get, Put and Delete.  See e.g. here for further details.  At present, the Post and Delete verbs are implemented.  Functionally, these create an activation and delete (i.e. deactivate) an activation.   This functionality allows the ISV to activate and deactivate a license using webservice calls made from a SaaS-based application to the Zentitle Licensing server and to specify a suitable computer ID (device ID) for these calls. 

At the start of each application run by a user, the Activate function is called to check if a license seat is available for the license code. The supplied device ID must be no greater than 20 characters and should be unique for the application run. We recommend using the HTTP session ID as the device ID in SaaS-based applications.   As this would entail different sessions having different device IDs, it is necessary, in order to prevent each session from consuming a new license seat, that SaaS licenses must operate in cloud-concurrent mode.  This adjustment is made automatically.  Note that it is for a similar reason that our VM detection, which necessitates the changing of the device ID with each license refresh, requires the license to be cloud-concurrent.

When the user logs out of the application or their session expires, the Deactivate function should be called to release the seat for another activation. If Deactivate is not called then the seat will be in use until the license code's lease period for this device ID expires.  The device will then be marked as reusable and can be used by a newly activating client.

Activation

Control Flow

Zentitle SaaS licensing is compatible with both our standard (device-based) and account-based licensing models.   In standard licensing, your user will have to supply a license code.  In account-based licensing, they will have to supply login credentials.

The user is assumed to enter this information on a web interface during an HTTP session with your application server.    On receipt of this information, in the case of standard licensing, your application server should simply call the Activate function described below with the supplied license code.   In account-based licensing, the login credentials will have to be validated.  How this occurs will depend on the authentication mode you choose.   Please see the account-based licensing documentation for further details about authentication modes.  

There are three authentication modes to choose from:

1. Zentitle Authentication: this is the simplest authentication mode where the credentials are passed to the Zentitle Licensing server in the Activate function and validated as part of the activation request.
   
2. Third-Party Authentication without token: here your application server would perform its own authentication using the supplied credentials.  If this is successful, the Activate function should be called.   
3. Third-party Authentication with Token: as with 2. except that, between authentication and activation, the user password should be updated on the Zentitle server to the token using the UpdateGroupUserPassword webservice.  This token should then replace the password in all subsequent transactions between the application and licensing servers.

If activation is permitted i.e. if the credentials/license code are validated and a license seat is available, then the end-user may proceed to use your web application.  If not, they should be logged out, with a possible error message, based on the return from the Zentitle server or your application server, e.g. invalid credentials or license code.

Activate function

End Point - https://my.nalpeiron.com/api/saaslicense

HTTP Verb – POST

Input

Output

Example Output

{
 "licensestatus": 3,
 "leaseperiodend": 2114402400,
 "errormessage": null,
 "errorcode": 0,
 "maintenanceenddate": 0,
 "subscriptionenddate": 0,
 "features": [
 {
 "name": "ACCEP",
 "type": "elementpool",
 "status": "on",
 "pool": 0,
 "value": "0"
 },
 {
 "name": "ACCFF",
 "type": "floatingfeature",
 "status": "on",
 "pool": 0,
 "value": "0"
 },
 {
 "name": "EPOOL",
 "type": "elementpool",
 "status": "on",
 "pool": 0,
 "value": "0"
 }
 {
 "name": "aszxczcasd",
 "type": "applicationagility",
 "status": "on",
 "pool": 0,
 "value": "4"
 }]
}

We recommend that, if the activation succeeds, the details of the entitlements (e.g. features enabled, subscription end date etc.) are stored in the session data so that they can be retrieved by your application  at any time without having to reactivate.

Example Function Calls

C#

var client = new RestClient("http://my.nalpeiron.com/api/saaslicense");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{ APIKey : \"XXXX\", CustomerID : \"XXX\", ProductID : \"XXXX\", LicenseCode : \"XXXXXXXXXXXXXXXXXXXXX\", DeviceID : \"XXXX\" }", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);} 

Curl

curl -X POST \
 http://my.nalpeiron.com/api/saaslicense \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache' \
 -d '{ APIKey : "XXXX", CustomerID : "XXXX", ProductID : "XXXXX", LicenseCode : "XXXXXXXXXXXXXXXXXX", DeviceID : "XXXX" }'

Deactivation

Control Flow

A Deactivation request should be made when either the session closes or expires.  The former will apply e.g. to your end-user logging out of the application whereas the latter will occur when the user is inactive for a (predetermined) period or the browser is closed.

Deactivate Function

End Point - https://my.nalpeiron.com/api/saaslicense

HTTP Verb – DELETE

Input

Output

Example Output

{
 "licensestatus": -6,
 "leaseperiodend": 0,
 "errormessage": "OK",
 "errorcode": 0,
 "maintenanceenddate": null,
 "subscriptionenddate": null,
 "features": null
}

Example Function Calls

C#

var client = new RestClient("http://my.nalpeiron.com/api/saaslicense");
var request = new RestRequest(Method.DELETE);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{ APIKey : \"XXXX\", CustomerID : \"XXXX\", ProductID : \"XXXXX\", LicenseCode : \"XXXXXXXXXXXXXXXXXX\", DeviceID : \"XXXX\" }", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Curl

curl -X DELETE \
 http://my.nalpeiron.com/api/saaslicense \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache' \
 -d '{ APIKey : "XXXX", CustomerID : "XXXX", ProductID : "XXXXX", LicenseCode : "XXXXXXXXXXXXXXXXXXXX", DeviceID : "XXXX" }'

Error Codes

Please see the error codes documentation for information about general licensing error codes.   One error code that can only arise in SaaS licensing is:

-999 - Failed to retrieve License - check License Status and error message