Manage licenses

The Knox Configure v2 APIs provide functionalities to manage Knox Configure licenses. This tutorial shows you how to retrieve licenses, retrieve license details, register a license, and delete a license.

Prerequisites

Ensure that you have the necessary permissions to manage licenses and obtain an authentication token. For more information, see Get started. Include your access token in the Authorization: Bearer <access_token> header of every request. Access tokens expire after 30 minutes.

Retrieve licenses

1. To retrieve a list of all licenses in your tenant, make a GET request to the /kc/v2/licenses endpoint. This operation requires the kc.license:view scope.

2. In the request, you can make use of the following optional query parameters:

   • licenseKeys — A list of license keys to filter by.
   • types — A list of license types to filter by. Possible values are SETUP_PER_DEVICE, SETUP_STAGGERED, DYNAMIC_PER_DEVICE, DYNAMIC_PER_SEAT, and DYNAMIC_LEGACY_EE.
   • status — A list of license statuses to filter by. Possible values are Pending, Expired, Active, Inactive, Terminated, and Deleted.
   • searchText — The text to search for in the fields specified in searchFields.
   • searchFields — A list of fields to search for the string specified in searchText. Possible values are licenseKey, name, and owner.
   • pageNum — Page number to retrieve. The indexing count starts at 0.
   • pageSize — Number of licenses to return at once. The default value is 25.
   • sortBy — The value that results are sorted by. Possible values are purchased, available, assigned, activated, activationEndDate, and updateTime.
   • sortOrder — The order by which results are returned. Possible values are ascending and descending.

For example, the following request retrieves all Active licenses of type SETUP_PER_DEVICE, sorted by updateTime in descending order:

GET /kc/v2/licenses?types=SETUP_PER_DEVICE&status=Active&sortBy=updateTime&sortOrder=descending&pageNum=0&pageSize=25

You can modify the query parameters to reflect the specific licenses you want to retrieve. For detailed response schema, see GET /kc/v2/licenses.

Retrieve license details

1. To retrieve the details of a specific license, make a GET request to the /kc/v2/licenses/{licenseKey} endpoint. This operation requires the kc.license:view scope.

2. In the request, specify the licenseKey as a path parameter.

For example, the following request retrieves the details of the license with key KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS:

GET /kc/v2/licenses/KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS

The response includes detailed information about the license, such as its name, owner, status, type, usage, seat counts (purchased, assigned, activated, available), activation information, and alert type. If no license is found for the specified key, the request returns 204 No Content with no response body. For detailed response schema, see GET /kc/v2/licenses/{licenseKey}.

Register a license

1. To register a new license in your tenant, make a POST request to the /kc/v2/licenses/licenseRegistration endpoint. This operation requires the kc.license:manage scope.

2. In the request body, you can use the following parameters:

   • licenseKey — The license key. This is a required parameter.
   • name — The name of the license. This is a required parameter.

For example, the following request body registers a license with the key KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS and the name My license:

{
  "licenseKey": "KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS",
  "name": "My license"
}

You can adjust the license key and name based on the license you want to register. For detailed response schema, see POST /kc/v2/licenses/licenseRegistration.

Delete a license

1. To delete a license from your tenant, make a DELETE request to the /kc/v2/licenses/{licenseKey} endpoint. This operation requires the kc.license:manage scope.

2. In the request, specify the licenseKey as a path parameter.

For example, the following request deletes the license with key KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS:

DELETE /kc/v2/licenses/KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS

Ensure that you check the code and message in the response for any errors and handle them appropriately for your app. See Error codes for the full list of Knox Configure error codes. For detailed specification, see Knox Configure API reference.