Consume licenses

License consumption is typically done using the 10Duke Scale License Checkout API. Through the API, you can handle the whole license consumption flow—checkout, heartbeat, and release—in both enforced and metered consumption mode.

You can also manually check out and release licenses in enforced consumption mode using the 10Duke Scale UI console. This allows experimenting with and testing the license checkout, and supporting customers individually when needed. Metered license consumption is not available in the UI console.

The articles in this section provide background information on how to use the License Checkout API to consume licenses. See below for an overview of how to check out a license, best practices to keep in mind, and examples. See the other articles in this section for information on the API requests and responses for checkout, heartbeat, and release, and refer to the API reference documentation for details.

It’s good to keep in mind that other alternatives and variations to the workflows are possible. The most feasible workflow is usually determined by the type of application you’re integrating and your business requirements.

Limitations

Licenses that have a license key can only be consumed using that license key. Key-based licenses cannot be consumed by license consumers of type person or device.

How to check out a license

The steps below give you an overview of how to handle the license consumption flow in your client application.

The general steps in the flow are similar in enforced and metered license consumption, although at the API level, metered consumption refers to starting and ending metered use instead of a checkout and release. You will see those terms in the API reference documentation, but to keep things simple, the rest of the documentation uses the general terms checkout and release for both consumption modes.

Your client application typically runs the license consumption flow using either OAuth ID token-based authorization or a license key.

The steps in the license consumption flow:

1. When the license consumption flow is initiated, the first step is to find out what licenses are available to the license consumer.

   Your application can do this through the License Checkout API with a GET /licensing/actions/describe-license-consumer-licenses request.

   If the license is consumed with a license key, there is always only one available license. However, if the license consumer is a user or device, there may be multiple licenses to choose from.

2. The next step is choosing which license to use. This will enable your application to specify the particular license to be consumed in the next step.

   When possible, we recommend that you let the end user choose which license to use. Typically UI-based applications are able to prompt the end user to select one. You may also be able to gain the end user’s input at some other stage, for example, when they first start using the application.

   It may be challenging to automate the choice over multiple licenses. When end user input is not available, your application could make the decision based on, for example, maximizing the features that the end user will get access to, or maximizing the length of the license validity.

3. To start the consumption of the license, your client application makes an API call to check out the license.

   This includes reporting the quantity that is being checked out, for example, 1 seat. With a seat-based license, 10Duke Scale applies the license model’s concurrency rules.

   10Duke Scale returns a license token in JSON Web Token (JWT) format. Your application verifies the token signature to ensure the token originated from 10Duke Scale.

   Your application also validates the token’s content, which includes checking what access was granted to the application or specific features in it. The application then allows the license consumer to access the application functionality accordingly.

4. After a successful checkout, the license consumer uses the application or service with a valid license.

5. While the license is checked out, your application makes periodic heartbeat API calls to acknowledge and authorize the continued consumption of the license.

   With a regular heartbeat, your application also keeps 10Duke Scale up to date on how much quantity has been consumed from the license.

   Your application receives a fresh license token at every heartbeat.

6. To end the consumption of the license, your application makes an API call to release the checkout.

Reporting quantity consumed from license

During the license consumption flow, your client application needs to report to 10Duke Scale the quantity consumed from the license.

Keeping 10Duke Scale up to date on the quantity consumed is especially important when use count or use time is being consumed. With a seat-based license, the quantity consumed is always 1 seat.

Your application reports the quantity consumed as follows:

1. At checkout, your application reports a quantity that is allocated from the license to the license consumer.

   In enforced consumption, the requested quantity cannot exceed the quantity available in the license. For example, if there’s not enough use time left, or all the available seats are already taken, the checkout fails.

2. At heartbeat, the application reports the actual quantity that has been consumed so far.

   In enforced consumption, the license must again have sufficient quantity available or the heartbeat fails.

   The client application can report either the total quantity consumed so far during the license checkout, or an incremental quantity consumed since the previous request (the checkout or the previous heartbeat). Based on the treatAsIncrementalQty flag in the request, 10Duke Scale then either records the reported quantity as the current total consumed quantity, or adds it on top of the current total consumed quantity.

3. When releasing the checkout, the application reports the final quantity that was consumed.

   • In enforced licensing, the final reported quantity is checked against the quantity that was preallocated, and any difference between them is either refunded to or deducted from the quantity consumed from the license.

   • In metered licensing, the final reported quantity is used for tracking the consumption.

Note: During the enforced consumption of a license that has use count or use time, your client application is responsible for tracking the quantity consumed against the quantity that was preallocated at checkout. (With a seat-based license, the allocated and consumed quantity are both always 1.)

Depending on your use case, you can then choose whether your client application will always prevent the consumed quantity from exceeding the preallocated quantity, or whether you want to allow overuse and accept the risk that at the time of release, the quantity consumed may exceed the remaining quantity available in the license.

Applying concurrency rules

With a seat-based license, the license model can define different limits on the concurrent usage of the license for an individual license consumer:

• Concurrent usage with the same seat

  The license model can set a limit either on devices or on application instances (but not both at the same time for the same license):

  • Limit how many devices (such as computers) one license consumer can use an application on at the same time, while still consuming only one seat from the license.

  • Limit how many application processes one license consumer can start at the same time, while still consuming only one seat from the license.

• Maximum concurrent seats

  Limit how many seats one license consumer can be consuming from the same license at the same time. This helps to avoid a situation where a single license consumer would be over-using a license while others suffer from seat unavailability.

Limits on concurrent usage are typically set for licenses that will be consumed by users or devices, but the same limits can be used with licenses consumed with a license key.

10Duke Scale applies the concurrency rules during the license consumption flow as follows.

1. When a checkout is requested for a license, 10Duke Scale checks if the license consumer already has an existing checkout for that license.

   Depending on whether a concurrency rule is applied on devices or application instances, the checkout request must provide either the hardware ID or the process ID.

2. If the license consumer has already checked out a seat, 10Duke Scale reuses the same seat if possible.

   The same seat can be reused if the device/application instance concurrency rule allows this (the limit is higher than 1) and the license consumer hasn’t exceeded the limit.

   For example, if 2 concurrent devices are allowed, and the user has checked out a seat on one device, they can now reuse that same seat on another device.

   It’s good to remember that there may be restrictions that prevent even using the same license for the new checkout. For example, a user may have checked out a seat from a license that only allows certain application versions, and they’re now doing another checkout using an application version that is not allowed. In this case, seat reuse is of course not possible, and the user needs to check out a seat from another license that allows this version.

3. If the seat in use cannot be reused, 10Duke Scale uses a new seat from the same license for the license consumer if possible.

   A new seat from the same license can be consumed if the license’s maximum concurrent seats rule allows this (the limit is higher than 1), the license consumer hasn’t exceeded the limit, and there’s an available seat in the license.

   For example, if the license allows a maximum of 2 seats per license consumer, and the license consumer has checked out one seat, they can now check out another seat from this license. After this, they won’t be able to check out any more seats from the same license.

   If using a new seat from the same license is also not possible, the next step is that 10Duke Scale tries another license, assuming the checkout request allows this (the request was for a product, not a specific license) and the license consumer has access to another valid license. The concurrency rules of that license are applied in the same way, starting from step 1.

See how to define concurrency rules in a product configuration.

Best practices

We recommend that you follow these best practices when implementing license consumption.

Include as many client application claims as possible

Even though most of the client application claims in checkout and heartbeat requests are optional, we recommend that you include as many claims as possible.

This gives flexibility for changing license model rules in the API to meet business requirements, and helps to avoid the need to redeploy and reinstall client applications.

Note: The same claims must be sent throughout the checkout flow: in the checkout request and in the heartbeat and release requests for that checkout.

Specify the ID of the license to be consumed

When possible, we recommend that your client application always first checks from 10Duke Scale which licenses are available to the license consumer, and then specifies the ID of the license to be consumed in the checkout request.

This allows you to keep control over which license is consumed in cases when there are multiple available licenses to choose from—this may be the case especially in B2B use cases.

If your application only provides the product name at checkout, and the license consumer has access to multiple licenses for that product, 10Duke Scale chooses the license to be consumed primarily based on available capacity.

Store the lease ID persistently

For a robust license release, we recommend that your client application stores the lease ID from the checkout and heartbeat requests persistently. The best option is to fully store the license token.

This helps to recover from possible crashes, power disruptions, and other unexpected errors. The lease ID is needed for sending a heartbeat and for ending the license use. Storing the lease ID persistently helps the client application to continue working and interacting with the License Checkout API as needed.

Use the periodic heartbeat

In enforced consumption, the client application should send a new heartbeat to update the consumed quantity before exceeding the quantity allocated at checkout. This applies to all quantity types, but a seat-based license’s quantity is always 1 and the purpose is only to validate the continued use of the seat.

In metered consumption, we recommend that within the limits of the maximum allowed frequency, the client application sends a new heartbeat as often as possible. The application can find the maximum allowed frequency in hbnbf in the license token.

Examples

Here are some examples of how you can handle the license consumption flow in different types of applications.

Example: License consumption for a UI-based application

This example describes how an application with a user interface can handle the license consumption flow. For more details, see the overview of the flow.

1. In identity-based use cases, first sign in the user using your identity provider to get an ID token. In license key-based cases, prompt the end user to enter a license key.

2. Retrieve the licenses that are available to the license consumer.

3. If applicable, visualize the available licenses to the end user in the UI, and allow them to select which license to use.

4. Check out the license using either the ID token or the license key.

5. The end user uses the application or service. Make periodic heartbeat calls.

6. Release the checkout when it’s no longer needed.

   We recommend that the application always releases the checkout, for example, when the end user has been idle for a long time, or logs out or closes the application. For example, in B2B use cases where a seat-based license is being shared by multiple end users, this helps to maximize seat availability for the end users.

Example: License consumption for a headless (no-UI) application

This example describes how a headless application with no user interface—in this case a consumer device with embedded software—can handle the license consumption flow. For more details, see the overview of the flow.

1. Configure and deploy the application. In this example case, you would embed a license key in the application during manufacturing.

2. Check out the license using the license key.

3. The application runs and performs its tasks. Make periodic heartbeat calls.

4. Depending on your use case, release the checkout when it’s no longer needed.

See more

• Check out a license

• Send a heartbeat to verify the license checkout

• Release a checkout

• Handle and store license tokens

• Set up the validation keys needed for license token verification