Last Modified January 26, 2021
  1. Home
  2. RESTful API
  3. Licenses Detail

Licenses Detail

  1. API Request
  2. API Response
  3. Request Examples
  4. Response Examples

 

Use the Licenses Detail API to retrieve detailed information on a specific License as a JSON string.

There are two options for this API:

HTTP Verb Element Syntax
POST URL https://api.softworkz.com/v1/Licenses/<productId>/<licenseId>
Body 
{
    "LicensePassword":"<password>",
    "UserIp":"<userIp>"
}

Validate the License Password, and if correct, respond with License Details

Use where you want to first authenticate the End-User using the License Password before presenting License information and allowing update of this information. For example, as part of a License Manager implementation.

You must provide the License Password and the End User IP Address as a JSON string in the body of the Request.

The IP Address is used to protect your implementation and this API from abuse and is only used to manage the IP Lockout feature of this API. The IP Lockout will be triggered after multiple invalid attempts in a given period, and a set cooling period will be enacted. Both are system-wide settings.
GET URL https://api.softworkz.com/v1/Licenses/<productId>/<licenseId>
Body (not required)

Responds with License Details

Use if no authentication of the End-User is required, such as:

  • to refresh the License information and device list for an authenticated User
  • the information will only be used within your internal processes
  • the information is presented to the End-User but with no option to change any settings.

Where:

Parameter Type Value Required Default
<productId> string the DNA ProductID Yes  
<licenseId> string the License Activation Code Yes  
<password> string the current License Password to authenticate the User (max 16 chars) Yes  
<userIp> string the User's IP Address, for protection against end-user abuse Yes  

The License Details contains information for every device activated on the License. For large Multi-User Licenses, use the following optional Request parameters in the URL to control the amount of information returned in the Response:

Key Name Type Key Value Key Default Description
page_no int <pageNumber> 1 returns the specified page of devices
page_size int <noOfDevicesPerPage> 25 maximum number of devices returned in the response

To assist in managing the presentation of the information, the Response will contain information on:

  • PageNo
  • PageSize
  • API Request URL's for FirstPage, LastPage, PreviousPage (if appropriate), NextPage (if appropriate)
  • TotalRecords
  • TotalPages

 

API Response

Success HTTP Status Code Description
200 OK License Detail JSON string is returned in Response
Error HTTP Status Code Description
400 Bad Request one of the parameters was invalid or missing - check error message in Response for details
401 Unauthorized Basic Authentication failed - verify that you are using the correct <clientId> and <apiKey> information in the Basic Authentication Header
403 Forbidden The <password> provided did not match the current License Password
404 Not Found The <productId> and/or the <licenseId> was not found
429 Too Many Requests You have exceeded the allowed maximum of API Requests in the period - check "X-RateLimit-Reset" for the number of seconds remaining before reset
500 Internal Error An error occured on the DNA Server - try again later. Tech Support has been notified

 

Examples of API Requests

POST Licenses Detail example - returns detailed information on the License

curl -v -X POST https://api.softworkz.com/v1/licenses/<productId>/TEST12345
-H "Accept: application/json"
-u "<clientId>:<API Key>"
-d ’{"LicensePassword:"12345","UserIp":"0.0.0.0"}’

GET Licenses Detail example - returns detailed information on the License

curl -v -X GET https://api.softworkz.com/v1/licenses/<productId>/TEST12345
-H "Accept: application/json"
-u "<clientId>:<API Key>"

 

Example of API Response with License Details

{
  "ProductId": "<productId>",
  "SoftwareDescription": "HelloWorld RAPID",
  "ProductSku": "HelloWorld",
  "LicenseCode": "TEST12345",
  "Status": "EXISTS ACTIVATION EXPIRED",
  "LicenseType": "NR (1)",
  "LicenseDescription": "Single-User / 2-device(s)",
  "LicenseCodeType": "Activation",
  "ActivationEmail": "...@softworkz.com",
  "ActivationDate": "2020-05-26T10:01:03",
  "ServerActivationDate": "2020-05-26T10:01:03",
  "OfflineActivation": false,
  "ExpiryNoDays": 90,
  "ExpiryDate": "2020-08-24T00:00:00",
  "LastReactivationDate": "2020-05-26T10:57:10",
  "ValidationLimitDate": "2020-06-25T10:01:03",
  "LicenseData": "",
  "Language": "EN",
  "MaximumDevices": 2,
  "NowDevices": 1,
  "PageNo": 1,
  "PageSize": 25,
  "FirstPage": "https://api.softworkz.com/v1/Licenses/<productId>/TEST12345?page_no=1&page_size=25",
  "LastPage": "https://api.softworkz.com/v1/Licenses/<productId>/TEST12345?page_no=1&page_size=25",
  "TotalRecords": 1,
  "TotalPages": 1,
  "Devices": [
    {
      "DeviceName": "MAC-Chrome",
      "DeviceId": "138d46869f6111ea907b000d3a126e34",
      "DeviceActivationDate": "2020-05-26T10:57:10"
    }
  ]
}

 

Example of API Error Response

{
  "Message": "Invalid ProductId format"
}