Introduction
Here we describe the REST API used for common operations in Zentitle SaaS Licensing. The following operations are implemented:
- License activation/deactivation
- Floating Feature check in/out
- Element Pool check in/out
- Consumption Token check in/out
We show how to perform the necessary setup involving creation of a suitable API key on the Zentitle dashboard. We then show how to include this in the required data for each API call.
https://documenter.getpostman.com/view/6590174/UVsFyo2c
To run tests or generate code in your preferred programming language in Postman, please replace the example values for various fields with the correct ones for your Zentitle account and products.
Calling the API
URL Format
The Zentitle SaaS Licensing REST API calls are to URLs having the following format:
Web API URL format - https://my.nalpeiron.com/api/<controller_name>
Creating a SaaS API Key
A SaaS API key is required to make calls to this API. These can be generated on the Zentitle dashboard by taking the following steps:
1. Login to my.nalpeiron.com
2. Navigate to "Settings" on the black navbar and then click "Webservices" from the drop down menu.
3. Navigate to the "API Keys" tab and click the "Generate New API Key" button.
4. Select the "SaaS" Key type from the drop-down menu and click "REQUEST" to generate an API Key and click "Save".
Web API Calls
Summary
Below are the basic Web API calls that are available.
| Controller Name | Action | Description |
| SaaSLicensing | POST | Obtains a license. |
| DELETE | Returns (deactivates) a license. | |
| SaaSFloatingFeature | POST | Checks out a floating feature seat. |
| PUT | Checks in a floating feature seat. | |
| SaaSElementPool | POST | Checks out a number of elements from a pool. |
| PUT | Checks in a number of elements from a pool. | |
| SaaSConsumptionToken | POST | Checks out a number of consumption tokens. |
| PUT | Checks in a number of consumption tokens. |
Required Headers
The following fields are used in headers in each API call:
| Header | Description | Example/Value |
|---|---|---|
| Authorization* | 'bearer' followed by a space then CustomerID and API key separated by a colon. |
e.g. "bearer 3133:u1dfe1ZlurloDE6c" |
| Content-Type* | The MIME type of the resource or the data. | Should be set to "application/json". |
| Account-Username** | Account-Based Licensing (ABL) username. | e.g. "JonDoe". Must be empty string if license code is supplied. |
| Account-Password** | ABL password. | e.g. "pass123". Must be empty string if license code is supplied. |
| ProductID* | Full 10-digit product ID. | e.g. "6763300100" |
* - Mandatory field.
** - Mandatory when license code is not supplied in request (see below.)
API Details
All DELETE methods are implemented to get input parameters from the request URI as Query String Parameters.
All characters in the input string that are passed as query string parameters should be URL encoded if required to avoid invalid character issues.
All POST and PUT methods are implemented to get input parameters from the request body.
Responses to the REST SaaS API are sent in JSON format. On success, the response will contain details as appropriate to the particular API call. When there is a failure due to an error, an error code will be provided along with the corresponding error message from the above table.
A license status is provided as part of the response where suitable, that is, where an activation or deactivation attempt has taken place and our licensing server has been contacted, with our records there determining the outcome: success or failure. A license status will generally not be provided under other circumstances, such as when the API call has failed at an earlier stage (e.g. authentication or data validation failure) or the API call does not relate to license activation or deactivation, e.g. it relates to feature check-out or check-in. If the API call is feature related, a feature status code with corresponding message will be provided instead. Details of possible license and feature status values are provided in this document.
SaaSLicensing
POST
At the start of each application run by a user, the POST 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.
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
| clientInfo | JSON array | Array whose elements consist of consumer registration data in the form of name/value pairs. The reserved names 'firstname', 'lastname', 'company' and 'email' are searchable on the Zentitle UI. Arbitrary (XML and JSON-friendly) additional fields may be added which will be visible on the UI. See the registration data documentation for further details. |
Output:
|
licenseStatus
|
string | Numerical status of license code. The value 4 indicates successful activation. | |
|---|---|---|---|
|
leasePeriodEnd
|
string | End of client lease period in Unix epoch time. | |
|
maintenanceEndDate
|
string | Maintenance end date in Unix epoch time. | |
|
subscriptionEndDate
|
string | Subscription end date in Unix epoch time. | |
|
features
(for each feature) |
name
|
string | The 5 character feature code. |
|
type
|
string | Type of feature: possible values: "normal","floatingfeature","elementpool","consumptiontoken","securestore" | |
|
status
|
string | Whether or not the feature has been enabled on the license code in question: "on" or "off". | |
|
maxAvailable
|
int |
total number of floating feature seats/pool elements/consumption tokens assigned to this license code. |
|
|
totalNumberCheckedOut
|
int |
total number of pool elements/consumption tokens checked out on this license code. |
|
|
applicationAgility
(for each AA variable) |
name
|
string | Application Agility variable field name. |
|
value
|
string | The set value for the Application Agility field. | |
Example Input (body)
{
"deviceID": "yuiyuIUYT",
"authType": "",
"clientInfo": [
{"name":"firstname","value":"John"},
{"name":"lastname","value":"Doe"},
{"name":"company","value":"Acme Widgets Inc."},
{"name":"email","value":"j.doe@acme.com"},
{"name":"testfield","value":"testval"}
],
"licensecode": "311300000290557169"
}
Example Output
Success
{
"licenseStatus": 4,
"leasePeriodEnd": 1633372425,
"maintenanceEndDate": 0,
"subscriptionEndDate": 1633770360,
"features": [
{
"name": "aaaaa",
"type": "normal",
"status": "on"
},
{
"name": "ACCEP",
"type": "securestore",
"status": "on"
},
{
"name": "ACCFF",
"type": "floatingfeature",
"status": "off",
"maxAvailable": 0
},
{
"name": "CM001",
"type": "normal",
"status": "on"
},
{
"name": "dsf",
"type": "normal",
"status": "on"
},
{
"name": "dtest",
"type": "normal",
"status": "on"
},
{
"name": "EFEAT",
"type": "elementpool",
"status": "on",
"maxAvailable": 100,
"totalCheckedOut": 0
},
{
"name": "ENGTS",
"type": "normal",
"status": "on"
},
{
"name": "EPOOL",
"type": "elementpool",
"status": "on",
"maxAvailable": 100,
"totalCheckedOut": 6
},
{
"name": "FCODE",
"type": "normal",
"status": "on"
},
{
"name": "FEAT1",
"type": "elementpool",
"status": "on",
"maxAvailable": 100,
"totalCheckedOut": 0
},
{
"name": "FEAT2",
"type": "floatingfeature",
"status": "on",
"maxAvailable": 100
},
{
"name": "FEAT4",
"type": "normal",
"status": "on"
},
{
"name": "FEAT5",
"type": "normal",
"status": "on"
},
{
"name": "FEAT6",
"type": "floatingfeature",
"status": "off",
"maxAvailable": 100
},
{
"name": "FLOAT",
"type": "floatingfeature",
"status": "off",
"maxAvailable": 100
},
{
"name": "NSA",
"type": "normal",
"status": "on"
},
{
"name": "sstor",
"type": "securestore",
"status": "on"
},
{
"name": "TOKEN",
"type": "consumptiontoken",
"status": "on",
"maxAvailable": 300,
"totalCheckedOut": 118
}
],
"applicationAgility": [
{
"name": "TEST1",
"value": ""
},
{
"name": "TEST2",
"value": ""
}
{
"name": "$CurrentActivations",
"value": "1"
},
{
"name": "$ActivationsAllowed",
"value": "99"
},
{
"name": "$UserActCount",
"value": "1"
},
{
"name": "$FeatureList",
"value": "<featurelist number=\"42\"><feature name=\"aaaaa\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"ACCEP\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_SECSTORE\" /><feature name=\"ACCFF\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FLOAT\" /><feature name=\"bbbb\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_SECSTORE\" /><feature name=\"CM001\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"dsf\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"dtest\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"EFEAT\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_ELEMPOOL\" /><feature name=\"ENGTS\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"EPOOL\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_ELEMPOOL\" /><feature name=\"FCODE\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"FEAT1\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_ELEMPOOL\" /><feature name=\"FEAT2\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FLOAT\" /><feature name=\"FEAT4\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"FEAT5\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"FEAT6\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FLOAT\" /><feature name=\"FLOAT\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FLOAT\" /><feature name=\"ghj\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"LSEC1\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_SECSTORE\" /><feature name=\"LSEC2\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_SECSTORE\" /><feature name=\"MOBD\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_ELEMPOOL\" /><feature name=\"nn1\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"NSA\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_FEAT\" /><feature name=\"RPGEN\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_TOKEN\" /><feature name=\"sstor\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_SECSTORE\" /><feature name=\"TOKEN\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_TOKEN\" /><feature name=\"tss\" status=\"FEATSTATE_DEACTIVATED\" type=\"FEATTYPE_SECSTORE\" /><feature name=\"TEST1\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_UDF\" /><feature name=\"TEST2\" status=\"FEATSTATE_ACTIVATED\" type=\"FEATTYPE_UDF\" /></featurelist>"
}
]
}
Failure
{
"message": "Subscription Expired",
"code": 0,
"licenseStatus": -116,
"details": {
"subscriptionStartDate": "",
"subscriptionEndDate": "1/24/2023 12:00:00 AM"
}
}
Note that in the above example, a license status is provided because the Zentitle licensing server was contacted and, on the basis of the stored, past expiry date, the activation could not proceed. However as the following example shows, no license status is set because the server was not contacted due to failure at the earlier, authentication stage:
Failure
{
"message": "Invalid AuthType",
"code": -12005
}
DELETE
A DELETE request will deactivate the license for that specified device. 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.
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
Output:
|
licenseStatus
|
string | Numerical status of license code. The value -6 indicates successful deactivation. | |
|---|---|---|---|
Example Output
Success
{
"licenseStatus": -6
}
This simply indicates that the license status is now -6, which corresponds to the license having been returned to our licensing server, which is what happens when a license is deactivated.
Failure
{
"message": "Invalid Activation",
"code": -12037,
"licenseStatus": 0
}
This happens when at attempt is made to delete a non-existent activation.
SaaSElementPool
POST
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
| featureCode | string | 5 character code of the feature to be checked out. |
| featureAmount | int | Number of elements to check out |
Output:
|
featureStatus
|
string | Feature status code message. See here for possible values. | |
|---|---|---|---|
|
statusCode
|
int | Feature status code value. | |
| totalCheckedOut | int | Total number of elements in this pool checked out on that license code. | |
Example Output
Success
{
"statusCode": 1,
"featureStatus": "FEATSTATE_ACTIVATED",
"totalCheckedOut": 170
}
Failure
{
"statusCode": -3,
"featureStatus": "FEATSTATE_DENIED",
"totalCheckedOut": 0
}
PUT
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
| featureCode | string | 5 character code of the feature to be checked in. |
| featureAmount | int | Number of elements to check in. |
Output:
|
featureStatus
|
string | Feature status code message. See here for possible values. | |
|---|---|---|---|
|
statusCode
|
int | Feature status code value. | |
| totalCheckedOut | int | Total number of elements in this pool checked out on that license code. | |
Example Output
Success
{
"statusCode": 1,
"featureStatus": "FEATSTATE_ACTIVATED",
"totalCheckedOut": 167
}
Failure
{
"statusCode": -3,
"featureStatus": "FEATSTATE_DENIED",
"totalCheckedOut": 0
}
SaaSFloatingFeature
POST
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
| featureCode | string | 5 character code of the feature to be checked out. |
Output:
| statusCode | string | Feature status code value. | |
|---|---|---|---|
| featureStatus | string | Feature status code message. See here for possible values. | |
Example Output
{
"statusCode": 1,
"featureStatus": "FEATSTATE_ACTIVATED"
}
PUT
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
| featureCode | string | 5 character code of the feature to be checked in. |
Output:
|
featureStatus
|
string | Feature status code message. See here for possible values. | |
|---|---|---|---|
|
statusCode
|
int | Feature status code value. | |
Example Output
{
"statusCode": 0,
"featureStatus": "FEATSTATE_DEACTIVATED"
}
SaaSConsumptionToken
POST
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
| featureCode | string | 5 character code of the feature to be checked out. |
| featureAmount | int | Number of tokens to check out. |
Output:
|
featureStatus
|
string | Feature status code message. See here for possible values. | |
|---|---|---|---|
|
statusCode
|
int | Feature status code value. | |
| totalCheckedOut | int | Total number of tokens checked out on that license code | |
Example Output
{
"statusCode": 1,
"featureStatus": "FEATSTATE_ACTIVATED",
"totalCheckedOut": 60
}
PUT
Input
| deviceID* | string | Identifier of device in question. Must be no more that 20 characters long. |
|---|---|---|
| licenseCode | string | License code in question. Required if ABL credentials are empty. |
| authType | string | ABL authentication mode. The default value, which applies if a value is not supplied, is the empty string "" which should be used when activating with a license code. Other possible values are "Standard" and "SSO" which correspond to standard and SSO Account-Based Licensing respectively. |
| featureCode | string | 5 character code of the feature to be checked in. |
| featureAmount | int | Number of tokens to check in. |
Output:
|
featureStatus
|
string | Feature status code message. See here for possible values. | |
|---|---|---|---|
|
statusCode
|
int | Feature status code value. | |
| totalCheckedOut | int | Total number of tokens checked out on that license code | |
Example Output
{
"statusCode": 1,
"featureStatus": "FEATSTATE_ACTIVATED",
"totalCheckedOut": 70
}
Featstate Messages
The following messages are returned in feature-related SaaS API calls according to the value of the feature status code.
| Feature status code | Featstate message |
|---|---|
| -5 | FEATSTATE_EXPIRED |
| -4 | FEATSTATE_UNAUTH |
| -3 | FEATSTATE_DENIED |
| -2 | FEATSTATE_UNKNOWN |
| -1 | FEATSTATE_ERROR |
| 0 | FEATSTATE_DEACTIVATED |
| 1 | FEATSTATE_ACTIVATED |