Using the following REST API, a license key can be set for an installation by providing its client_id and the license key to be set.

NOTE: This is an additional feature made available alongside the existing functionality of collecting the license key from the SDK integration, which remains unchanged and continues to function as expected. For more information, please refer to the corresponding SDK documentation (for example, Usage Intelligence 5.6.1 C++ for Windows SDK Developer Guide).

Authenticate

To authenticate with Usage Intelligence, follow the instructions in the Usage Intelligence Reporting API 3.0 Guide.

API to Set License Key

The user needs to have admin privileges on the product to set license key using this API.

API Endpoint

/v3/products/update-client/set-license-key/<product_id>

API Type

POST

Headers

Refer to the header requirements as per any POST API in the Usage Intelligence Reporting API 3.0 Guide.

JSON Input

{
  "client_id": "Installation’s_client_id",
  "license_key": "license_key_to_set"
}

Response Format

{
  "license_key_status": “Status of the transaction: successful or relevant error if the request failed ",
  "license_flags_status":"LICENSETYPE:7\nEXPIRED:1\nACTIVATED:1\nBLACKLISTED:1\nWHITELISTED:1"
”
}

Numeric Value of the LICENSETYPE

The numeric value of the LICENSETYPE indicates the following:

Numeric Value of the Remaining Flags

The numeric value of the remaining flags (EXPIRED, ACTIVATED, BLACKLISTED, WHITELISTED) indicates the following:

License type and flags will be set based on the License Key Registry Operation Mode: Client Managed, or Server Managed. For more information on the client and server modes, refer to Software License Usage Tracking - Part 3.

NOTE: The above documentation explains the operations that can be performed using Analytics SDK, but the definition of client and server mode remains the same even when setting license key utilizing this REST API.

Server Managed

Usually, keys are added to the registry either from the Usage Intelligence dashboard or using the V3 API.

Possible Scenarios

1. License Key Already Exists in the Key Registry
   If the existing key is set using the API, the license key will be set for the installation. The license type and status flag values will be copied to the installation as set in the key registry.
   
   
2. License Key Does Not Exist in the Key Registry
   1. Any key set using the API is added to the registry with the type as unknown and the remaining flags set to false.
   2. The same type and flags will be copied to the installation. If the type or flags in the key registry are changed in the future, future key set operations will use the changed type or flag values for the installation.

Client Managed

Usually, keys are auto collected from the installation through SDK syncs.

Possible Scenarios

1. License Key Already Exists in the Key Registry
   If the existing key is set using the API, the license key will be set for the installation, but with the license type as unknown and the remaining remaining flags set to false irrespective of values in the registry.
   
   
2. License Key Does Not Exist in the Key Registry
   Any key set using the API will be added to the registry with the license type as unknown and the remaining flags set to false. The same type and flag values will be copied to the installation. If the type and flag values in the key registry are changed in the future, future key set operations will still use the type as unknown and flags as false.
   
   
3. Mixed Mode
   1. The individual type or flag set to server mode will exhibit the server mode behavior.
   2. The individual type or flag set to client mode will exhibit the client mode behavior.

CAUTION: Kindly review the documentation in detail. If feasible, consider evaluating this feature using a test product or by creating a new product and initiating the free trial. This approach will facilitate a comprehensive understanding prior to performing these operations in a production environment. Please ensure that all key set actions performed are documented with their corresponding outcomes for future reference.

Example: Server Managed Mode Where the License Key Set Using the API Exists in the Registry

1. Open the License Key Registry page in the Usage Intelligence dashboard, and add a key named existing-key-added-in-registry-set-to-installation-1663160CB7A4DE-while-operating-in-server-mode and save it. “1663160CB7A4DE” is the client ID of an installation (open the Client Profile page to explore).
   
   
2. Observe the following:
   
   • License Type is set to Purchased.
   • Activated is selected.
   • Allowed is selected.
     
     
3. The new license key is listed on the License Key Registry page:
   
   
4. Sort keys by added date and observe:
   • The key you just added is listed.
   • The install count is 0.
     
     
5. Next, use Postman to call the APIs.
   
6. Observe the following:
   • Authentication is performed on the first tab.
   • Input is provided.
   • License key settings are set to server mode as shown in the earlier image.
     
     
7. Next, click Send.
   
   
8. Observe the following:
   • Response status is 200 OK.
   • License key has been set successfully.
   • Verify numerical values of the type and flags as mentioned in the document.
   • (Whitelisted is also known as Allowed.)
   • (Blacklisted is also known as Blocked.)
     
     
9. Verify by fetching the client profile of the installation “1663160CB7A4DE” as shown below
   
   
10. Refresh the License Key Registry and observe that the install count has been incremented by 1 for this license key.