Check out a license

The checkout is used to start the consumption of a license for a license consumer.

You can use the 10Duke Scale License Checkout API to check out a license in enforced license consumption mode or to start metered consumption of a license. To consume a license in enforced mode, you can also check it out in the UI console.

For background, see an overview of the license consumption flow, and information on the limitations and best practices related to checking out licenses.

Before you start

• If you’re checking out a license for a license consumer of type person or device, make sure the license consumer has access to the license. When checking out using the UI console, the license consumer must also have an email address defined.

• Make sure that license token validation keys have been set up, and that the client application has access to the public key needed for verifying the license token in the checkout response.

Checkout request

The API reference provides the full documentation on the request parameters used to carry the client application claims for the license checkout.

The information here is intended to help you to read the API documentation and, for example, to understand how to use checkout arguments that apply to a specific license in the checkout request.

Client application claims

In a license checkout request, client application claims contain key-value type of information on the license consumer, the client application, and the environment the client application runs in. This information plays a key role when calling the License Checkout API.

Client application claims are used to bind license checkouts to a specific context of a user and a client application. This contextual binding is often called anchoring.

Certain license model rules require certain client application claims to be present in order to qualify. Missing claims in a checkout request result in a “license not found” response (the API ignores licenses that cannot be checked out due to a mismatch in rules and input information).

Request header parameters

The following are the most significant client application claims provided in the request header parameters.

Request body parameters

The request body parameters specify claims that apply to a specific license being checked out, such as the requested product and the preallocated quantity to be consumed.

Note: In addition to the product name, when possible the checkout request should include the license ID to identify the license to be consumed.

The clientVersion request body parameter can be used to specify a version for a specific application component and the license being checked out. This overrides the version in the cliVersion header parameter, which by default applies to the whole checkout.

Checkout response

If the license checkout is successful, 10Duke Scale returns a signed JSON Web Token (JWT) license token.

In principle, the license token is valid as long as the license is. 10Duke Scale sets the license’s validity end date and time as the token’s expiration time when creating the token. If the license’s validity end date is changed, your application receives a token with an updated expiration time at the next heartbeat.

The client application needs to store the license token and verify the JWT signature and content in order to allow the user to use the application. See more on how to handle and store license tokens.

For information on error responses, see information on the general error response model and license consumption errors.

License token (JWT) claims

The license token can contain the JWT claims listed below: standard JWT claims, additional Internet Assigned Numbers Authority (IANA) registered JWT claims, and JWT claims specific to 10Duke Scale.

See more details on standard JWT claims in RFC 7519 and JWT claims registered with IANA.

Standard JWT claims

Additional registered JWT claims

10Duke Scale-specific JWT claims

Example checkout response

This is an example of a successful response to a license checkout.

{
  "iat": 1714986679,
  "jti": "4c415be8-c3cb-47a1-acb0-d21868bc106c",
  "iss": "10Duke",
  "exp": 1751327999,
  "nbf": 1714986679,
  "toe": 1714986679,
  "leaseId": "1714997479.djEuMC4w.e.M2NjNWFjZjM1NzlmNDA0ZmIyYTljNjZkYjk4ODcyZTI=",
  "hbnbf": 1714997479,
  "productName": "ThreeDee",
  "type": "PRECONFIGURED_PRODUCT",
  "productConfigurationName": "ThreeDee Team",
  "licenseId": "1fc8e4e5-1dcd-4db9-a45f-c1c0c724815b",
  "qtyPrealloc": 0,
  "qtyVerified": 1,
  "qtyDimension": "SEATS",
  "qtyEnforcementType": "ENFORCED",
  "features": [
    "simulate",
    "render",
    "measure"
  ],
  "licenseConsumerId": "dd30afb4-8417-2646-89bc-163e0e2f86ca",
  "status": "success",
  "clientClaims": {
    "cliHwId": "xefainge8uiGhoo4aemieK1x",
    "cliHwLabel": "MyDesktop",
    "cliInstallationId": "644b92b9-23b0-42ee-a325-8dd9071f8d03",
    "cliLang": "en",
    "cliVersion": "1.0.1"
  }
}

Check out licenses in the UI console

To check out a license:

1. In the left sidebar, go to LICENSING > Customers.

2. Find the customer whose license you want to check out, click the three-dot menu for the customer, and select Licenses.

   The list of that customer’s licenses opens.

3. Click the three-dot menu for the license, and select Checkout. The license checkout form opens.

4. If you’re checking out a license for a license consumer of type person or device, enter the license consumer’s email address and click Verify to verify it.

   

   If you’re checking out a license that has a license key, the form shows the license key at the top instead.

   

5. In Quantity, define the quantity that you’re checking out from the license.

   • For a license that has use count or use time, define the preallocated quantity.

   • For a seat-based license, you can only check out one seat at a time.

6. In Client application claims, define the required and relevant client application claims.

   These are the same client application claims as in a checkout done through the API. See information on the most important client application claims, and the full parameter reference for the relevant API operation (enforced mode) in the API reference.

7. Click Checkout. A JWT license token is generated and displayed.

8. Click Download Token to download the license token file.

Check out licenses through the API

Use the following License Checkout API operations to check out licenses for a license consumer of type person (user) or device or using a license key:

Next steps

If you’re using the UI console to check out licenses, you can deliver the downloaded tokens to end users or use them in your devices in manufacturing. The client application is still responsible for verifying that the license token is valid.