Provision a trial license

A trial license means that the customer acquires a short-term license that gives them access to use your software for a limited period of time.

In 10Duke Enterprise, a trial license usually has a limited validity period with an end date defined. Trial licenses can be used with both B2B and B2C customers.

To prevent the abuse of trial licenses, you can prevent a customer from using the same trial license repeatedly on the same device. See more about the trial license constraint.

Enforcing the trial license constraint requires the following:

  • The license model associated with the license must use ConsumptionLockConstraint to create a locking based on the device.

  • The license provisioning request must specify the lock scope that is used for the locking together with the device’s hardware ID.

    If the product package (or any licensed item in it) uses a license model that applies the ConsumptionLockConstraint rule, the provisioning request must always include the lockScope field. This means that in cases where you’re using the same product package for provisioning commercial licenses, set lockScope to None to disable the locking.

  • Your client application must include the hardware ID of the device in the license consumption request.

This article explains how to provision (grant) a trial license using the 10Duke Entitlement Management REST API. For background, see how license provisioning through the API uses the concept of a transaction.

The article assumes you have connected your client application to 10Duke Enterprise and implemented license consumption for it.

API operations

10Duke Entitlement Management REST API operations:

Item URL (relative, prepend the environment base URL)
Provision a license to an organization POST /organizations/{orgId}/license-transactions
Provision a personal license to a user POST /users/{userId}/license-transactions

Example

This example shows how to provision a trial license to a consumer customer.

The example uses the following business case:

  • Product provided on trial: CutXPro, a B2C desktop software application that allows end users to crop elements from photographs

  • Quantity granted: 1 license

  • Product package in 10Duke Enterprise: Name CutXPro, product ID 0aa228a2-d3bc-4934-9069-658333c03780

  • Customer: A B2C customer

  • License terms: The license is granted for a fixed term of 1 month

This example provisions a seat-based license, so the product package has a licensed item configured to grant 1 seat, and the associated license model has SeatCountConstraint enabled.

Request example

Send a POST request to users/{userId}/license-transactions. See the API reference for details on the API path parameters, request body, and response schemas.

This example request uses curl (line breaks added for display purposes).

The request specifies licenseValidFrom and licenseValidUntil dates to set a 1-month validity for the trial license, and lockScope to specify a lock scope for preventing the abuse of trial licenses.

curl --request POST
   --url <API_base_path>/users/me/license-transactions
   --header 'content-type: application/json'
   --data '{"transaction":{"type":"Trial","externalId":"0000004556786","items":[{"externalId":"0001","productId":"0aa228a2-d3bc-4934-9069-658333c03780","quantity":1,"lockScope":"cutxpro-trial","licenseValidFrom":"2024-04-19T14:12:22.012Z","licenseValidUntil":"2024-05-19T14:12:22.012Z"}]}}'

Response example

This sample response shows information that the response body can contain:

{
   "transaction": {
      "id": "8ec39f9d-f739-4bc1-aa55-8cb712e50adb",
      "type": "Trial",
      "externalId": "0000004556786",
      "processed": "2023-02-19T14:12:22.010Z",
      "items": [{
         "id": "",
         "externalId": "0001",
         "productId": "0aa228a2-d3bc-4934-9069-658333c03780",
         "quantity": 1,
         "lockScope": "cutxpro-trial",
         "licenseValidFrom": "2024-04-19T14:12:22.012Z",
         "licenseValidUntil": "2024-05-19T14:12:22.012Z",
         "licenses": [{
            "id": "48e04c21-1fae-4ddf-ab5a-e0644039c81e",
            "validFrom": "2024-04-19T14:12:22.012Z",
            "validUntil": "2024-05-19T14:12:22.012Z",
            "active": true,
            "entitlementId": "6bde22fa-ecd4-4017-9b61-d661c33ba353",
            "licensedItem": {
               "id": "75151a68-fee2-436e-bfa7-3d9e5b94668d",
               "name": "CutXPro",
               "displayName": "CutXPro"
            },
            "licenseModelId": "1db0c182-70c4-4a51-8326-54ce29138303",
            "licenseModelName": "License_Model_for_Personal_License",
            "seatsTaken": 0,
            "seatsReserved": 0,
            "seatsTotal": 1,
            "lockScope": "cutxpro-trial",
            "seatCountCredits": [{
               "id": "9b6cce7d-eef2-4953-ba31-390932052501",
               "validFrom": "2024-04-19T14:12:22.012Z",
               "validUntil": "2024-05-19T14:12:22.012Z",
               "active": true,
               "licenseId": "48e04c21-1fae-4ddf-ab5a-e0644039c81e",
               "licenseTransactionItemId": "e0588c33-7055-4b28-8ec6-9e92c6f3b94f",
               "seatCount": 1,
               "seatsConsumed": 0
            }]
         }]
      }]
   }
}

Next steps

  • In the above example case, the consumer user now has a trial license and will be able to use the software application for 1 month. When the trial license expires, the user can no longer access the application. You can make the option to purchase the license available to the user through your customer-facing e-commerce or payment provider platform.

    If you provisioned a trial license to an organization, authorize the organization’s users or device clients to consume the license. The license was created in the organization’s default entitlement, so add the users or device clients to a user or device client group that has access to that entitlement. (This can also be done in advance.) You can do this through the 10Duke Identity Management REST API and in the 10Duke SysAdmin tool.

  • If the customer decides to purchase the product based on the trial, you can let the trial license expire, and provision the new commercial license with the same product package and disable locking by setting lockScope to None.

    Another option is that you update the trial license to continue the validity time and to disable the locking by setting lockScope to None. See the update operations PUT /organizations/{orgId}/license-transactions and PUT /users/{userId}/license-transactions.

On this page