Retrieving and Searching License Keys from the Key Registry
This request is used in order to get a list of license keys known by the Usage Intelligence servers along with their details. This is also used to search the key registry for a particular key or set of keys either by the key value itself or by another property such as by the expiry date or the assigned license type.
| • | Request/Response Parameters Summary |
| • | Example Request |
| • | Example Response |
Request/Response Parameters Summary
POST /licenseKeys/listKeys
The request and response are both JSON objects. The following is a summary of the properties inside the request and response objects.
| • | Request JSON Object Properties |
| • | Request Headers. Response Headers, and Status Codes Properties |
| • | Response JSON Object Properties |
Request JSON Object Properties
The following is a summary of the properties inside the request JSON object.
|
Property |
Description |
||||||||||||
|
user (string) |
The username of your Usage Intelligence user account. Required only for non-cookie authentication. |
||||||||||||
|
sessionId (string) |
The sessionId obtained via POST /auth/login. Required only for non-cookie authentication. |
||||||||||||
|
productId (integer) |
The product ID on which this request is being done |
||||||||||||
|
filters (object) |
Optional JSON object to apply filters to retrieve subset of the keys on the server. Can contain any number of the following members: |
||||||||||||
|
licenseKey (object) |
Filter by license key
|
||||||||||||
|
addedDate (object) |
Filter based on the date added to the key registry
|
||||||||||||
|
expiryDate (object) |
Filter based on the date the key is set to expire
|
||||||||||||
|
filters (object) (continued) |
autoCollected (boolean) |
Whether the keys to show were automatically collected by the SDK or not (uploaded to the server by the vendor) |
|||||||||||
|
overQuotaCount (object) |
Filter based on whether the key is oversubscribed and by how much. A negative number means that the key is running under-quota meaning that the user may still use it on more machines. The number 0 means that the quota has all been used but it hasn’t been exceeded. Positive numbers mean that the key is over-subscribed.
|
||||||||||||
|
licenseType (object) |
Filter based on the license type assigned to the key
|
||||||||||||
|
licenseStatus (array) |
Filter based on the license status flags assigned to the key. This filter contains an array of objects. Each object defines a set of flags and their respecive value. The flags in each object are “ANDed” together. If the array contains multiple objects, these objects are “ORed” together. In the example above, the keys have to be either “not activated” and “not expired” OR “activated” and “not blacklisted”. Each object in the array can contain any number of the following members:
|
||||||||||||
|
sorting (object) |
Optional JSON object to apply sorting on the list of keys. Should contain the following members:
|
||||||||||||
|
paging (object) |
Optional JSON object to specify the maximum number of keys to retrieve and how many to skip. Should contain the following members:
|
||||||||||||
Request Headers. Response Headers, and Status Codes Properties
The following is a summary of the properties.
|
Property |
Description |
|||||||||
|
Request Headers |
|
|||||||||
|
Response Headers |
|
|||||||||
|
Status Codes |
|
Response JSON Object Properties
The following is a summary of the properties inside the response JSON object.
|
Property |
Description |
||||||||||||
|
status (string) |
Contains OK if successful or SYNTAX ERROR or AUTH ERROR |
||||||||||||
|
reason (string) |
Present only if status is not OK. Contains error message (reason) |
||||||||||||
|
returnedKeysCount (integer) |
Present only if status is OK. Contains the number of keys returned in this response |
||||||||||||
|
matchingKeysCount (integer) |
Present only if status is OK. Contains the total number of keys matching the supplied filters |
||||||||||||
|
results (array) |
Present only if status is OK. Contains a JSON object for each license key returned. Each object contains the following: |
||||||||||||
|
licenseKey (string) |
The license key as supplied to the Usage Intelligence SDK |
||||||||||||
|
licenseType (string) |
The license type such as purchased, freeware, etc. |
||||||||||||
|
licenseStatus (object) |
A JSON object containing the 4 license status flags:
|
||||||||||||
|
expiryDate (string/null) |
The date the key is set to expire formatted as YYYY-MM-DD. If an expiry date is not set, this value contains null. |
||||||||||||
|
installQuota (integer) |
The maximum number of installations allowed to use this key |
||||||||||||
|
installCount (integer) |
The number of installations using this key |
||||||||||||
|
overQuotaCount (integer) |
This field is computed by subtracting the installQuota from the installCount. If a key is not being over-used, this number will be a negative number or 0. If it is running over-quota, it will show a positive number. |
||||||||||||
|
addedDate (string) |
The date and time when this key was added to the key registry formatted as YYYY-MM-DDThh:mm:ss |
||||||||||||
|
autoCollected (boolean) |
Whether the key was automatically collected by the SDK or not (uploaded to the server by the vendor) |
||||||||||||
|
results (array) (continued) |
lastEditedDate (string/null) |
The date and time when this key was last edited formatted as YYYY-MM-DDThh:mm:ss. If this key has been auto-collected and never edited, this field will contain a null value. |
|||||||||||
|
lastEditedBy (object/null) |
A JSON object containing the details about the user who last edited this key. If this key has been auto-collected and never edited, this field will contain a null value. If the user who last edited this key was removed from Usage Intelligence after requesting account deletion, this will contain an empty JSON object.
|
||||||||||||
|
notes (string) |
|||||||||||||
POST /licenseKeys/listKeys HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json
{
"user": "testuser@test.com",
"sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
"productId": 12345678901,
"filters": {
"overQuotaCount": {
"type": "numberRange",
"min": 1
},
"addedDate": {
"type": "dateRange",
"min": "2017-06-21"
},
"licenseStatus": [
{
"activated": false,
"expired": false
},
{
"activated": true,
"blacklisted": false
}
]
},
"sorting": {
"field": "overQuotaCount",
"order": "descending"
},
"paging": {
"startAt": 20,
"limit": 10
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "OK",
"returnedKeysCount": 2,
"matchingKeysCount": 22,
"results": [
{
"licenseKey": "14e7821b-694d-4d2d-90c2-adb10c07df0c",
"licenseType": "purchased",
"licenseStatus": {
"activated": false,
"blacklisted": true,
"expired": false,
"whitelisted": false
},
"expiryDate": "2018-05-17",
"installQuota": 2,
"installCount": 27,
"overQuotaCount": 25,
"addedDate": "2017-07-24T08:18:28",
"autoCollected": false,
"lastEditedDate": "2017-07-24T08:10:19",
"lastEditedBy": {
"name": "Revulytics",
"surname": "Demonstration",
"email": "demo@revulytics.com"
}
},
{
"licenseKey": "70cda86c-46c3-4399-b358-9e762ed1fcf5",
"licenseType": "unknown",
"licenseStatus": {
"activated": false,
"blacklisted": true,
"expired": false,
"whitelisted": false
},
"expiryDate": null,
"installQuota": 1,
"installCount": 501,
"overQuotaCount": 500,
"addedDate": "2017-07-24T08:18:30",
"autoCollected": true,
"lastEditedDate": "2017-07-24T08:10:19",
"lastEditedBy": {
"name": "Revulytics",
"surname": "Demonstration",
"email": "demo@revulytics.com"
}
}
]
}