Developer Zone

License Key Registry Management

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 Revulytics 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

POST /licenseKeys/listKeys
Request JSON Object:
 
  • 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
      • type (string) – The data type of the value. Can be string, stringArray, or regex
      • value (string/array) – Contains either a string with the full license key, a list of strings with full license keys, or a string containing a regular expression.
    • addedDate (object) – Filter based on the date added to the key registry
      • type (string) – The data type of the filter. Can be date or dateRange.
      • value (string) – To be used only if type is date. Should contain a single date formatted as YYYY-MM-DD
      • min (string) – To be used if type is dateRange. Should contain the minimum date formatted as YYYY-MM-DD. Can be used by itself or in conjuction with max.
      • max (string) – To be used if type is dateRange. Should contain the maximum date formatted as YYYY-MM-DD. Can be used by itself or in conjuction with min.
    • expiryDate (object) – Filter based on the date the key is set to expire
      • type (string) – The data type of the filter. Can be date or dateRange
      • value (string) – To be used only if type is date. Should contain a single date formatted as YYYY-MM-DD.
      • min (string) – To be used if type is dateRange. Should contain the minimum date formatted as YYYY-MM-DD. Can be used by itself or in conjuction with max.
      • max (string) – To be used if type is dateRange. Should contain the maximum date formatted as YYYY-MM-DD. Can be used by itself or in conjuction with min.
    • 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.
      • type (string) – The data type of the filter. Can be number or numberRange.
      • value (integer) – To be used only if type is number. Should contain a single number.
      • min (integer) – To be used if type is numberRange. Should contain the minimum overQuota number to include. Can be used by itself or in conjuction with max. If max is present, the min value should be smaller than max.
      • max (integer) – To be used if type is numberRange. Should contain the maximum overQuota number to include. Can be used by itself or in conjuction with min. If min is present, the max value should be greater than min.
    • licenseType (object) – Filter based on the license type assigned to the key
      • type (string) – The data type of the filter value. Can be string or stringArray
      • value (string/array) – Contains either a string with the license type, or a list of strings with license types to include
    • 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:
      • activated (boolean) – Whether the key is set to activated
      • blacklisted (boolean) – Whether the key is set to blacklisted
      • expired (boolean) – Whether the key is set to expired
      • whitelisted (boolean) – Whether the key is set to whitelisted
  • sorting (object) –

    Optional JSON object to apply sorting on the list of keys. Should contain the following members:

    • field (string) – The field by which to sort. Can be addedDate or overQuotaCount. Default is addedDate.
    • order (string) – The order by which to sort. Can be ascending or descending. Default is ascending.
  • paging (object) –

    Optional JSON object to specify the maximum number of keys to retrieve and how many to skip. Should contain the following members:

    • startAt (integer) – The number of keys to skip from the beginning. Default is 0.
    • limit (integer) – The maximum number of keys to include in the response. Default is 100. Maximum allowed is 1000.
Request Headers:
 
  • Content-Type – Can be set to application/json or text/javascript
  • Accept – Should be set to text/javascript
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • 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:
      • activated (boolean) - Whether the key is set to activated
      • blacklisted (boolean) – Whether the key is set to blacklisted
      • expired (boolean) – Whether the key is set to expired
      • whitelisted (boolean) – Whether the key is set to whitelisted
    • 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)
    • 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.
      • name (string) - The name of the user who last edited this key
      • surname (string) - The surname of the user who last edited this key
      • email (string) - The authentication email address of the user who last edited this key
    • notes (string) – A string value used to store reference notes about this key.

Example request:

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": "2014-06-21"
        },
        "licenseStatus": [
            {
                "activated": false,
                "expired": false
            },
            {
                "activated": true,
                "blacklisted": false
            }
        ]
    },
    "sorting": {
        "field": "overQuotaCount",
        "order": "descending"
    },
    "paging": {
        "startAt": 20,
        "limit": 10
    }
}

Example response:

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": "2015-05-17",
                      "installQuota": 2,
                      "installCount": 27,
                      "overQuotaCount": 25,
                      "addedDate": "2014-07-24T08:18:28",
                      "autoCollected": false,
                      "lastEditedDate": "2014-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": "2014-07-24T08:18:30",
                      "autoCollected": true,
                      "lastEditedDate": "2014-07-24T08:10:19",
                      "lastEditedBy": {
                          "name": "Revulytics",
                          "surname": "Demonstration",
                          "email": "demo@revulytics.com"
                      }
                  }
             ]
}

Updating and inserting new keys in the key registry

This request is used in order to update existing keys or to insert new keys into the key registry. Keys can be updated one by one or in batch. A single batch can contain both new and existing keys to be inserted or updated accordingly.

Request/response parameters summary

POST /licenseKeys/updateKeys
Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account
  • sessionId (string) – The sessionId obtained via POST /auth/login
  • productId (integer) – The product ID on which this request is being done
  • keyUpdates (array) –

    Array containing a number of JSON objects each containing a license key and the fields to be updated. The license key is the only compulsory value. All the rest are optional as you may send a subset of the fields. If a license key is already present in the key registry, the values that are not sent in this object are left untouched in the key registry. If the key is not presnt and an insert is taking place, default values are applied to the missing fields. The object members are as follows:

    • licenseKey (string) – The license key to be updated or inserted to the key registry. This value is compulsory.
    • licenseType (string) – The license type such as purchased, freeware, etc.. Default is unknown.
    • licenseStatus (object) – A JSON object containing the 4 license status flags or a subset:
      • activated (boolean) - Whether the key is to be set as activated. Default is false.
      • blacklisted (boolean) – Whether the key is to be set as blacklisted. Default is false.
      • expired (boolean) – Whether the key is to be set as expired. Default is false.
      • whitelisted (boolean) – Whether the key is to be set as whitelisted. Default is false.
    • expiryDate (string/null) – The date the key is set to expire formatted as YYYY-MM-DD. A null value may also be sent to set this field as *null. Default is null.
    • installQuota (integer) – The maximum number of installations allowed to use this key. Default is *1.
    • notes (string) – A string value used to store reference notes about this key. Default is a zero-length (empty) string.

Example request:

POST licenseKeys/updateKeys  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "keyUpdates": [
        {
            "licenseKey": "70cda86c-46c3-4399-b358-9e762ed1fcf5",
            "licenseType": "purchased"
        },
        {
            "licenseKey": "14e7821b-694d-4d2d-90c2-adb10c07df0c",
            "licenseStatus": {
                "whitelisted": true,
                "activated": true,
                "expired": false
            },
            "expiryDate": "2016-10-31"
        }
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "insertedKeys": 0,
  "rejectedKeys": 0,
  "updatedKeys": 2
}