Issue licenses using activation codes

You can use activation codes to issue licenses when a customer or end user first uses your application.

You generate activation codes with preconfigured license details, and a particular activation code can be redeemed later by any customer to get a license and access your application.

The 10Duke Scale License Management API provides the features needed for generating and managing activation codes, issuing licenses based on the activation codes, and tracking the use of the activation codes.

What is an activation code?

In practice, an activation code consists of two parts: the code itself (a unique character string) which you provide to the customer, and the activation code’s “configuration” which is stored in 10Duke Scale.

This latter part, the activation code’s configuration, holds the information for issuing a specific kind of a license when a customer or end user redeems the code:

• Each activation code specifies the product configuration to be used for issuing the license. The product configuration determines, for example, what features the license allows, whether it grants seats, a use count, or use time, and whether license consumption is enforced or metered.

• Each activation code also defines when the license will be valid, how much quantity will be granted in the license (such as the number of seats), and whether a license key is generated for consuming it. The license validity can be fixed to a specified timeframe, or set to start running from the time the activation code is redeemed.

• You can limit the time period during which an activation code can be redeemed. It’s good to note that if you don’t set an expiry date for your activation codes, they may potentially be redeemed a long time after you distributed them.

Activation codes are typically managed in batches, but you can also generate and manage individual activation codes if needed. Generating activation codes individually (for example, per purchase) allows more detailed targeting in aspects such as when a particular activation code is valid, or how much quantity is granted in the license.

Security

The activation code provided to a customer is a unique complex character string, and doesn’t contain any encoded information. There’s no algorithm that would enable generating activation codes outside of the 10Duke Scale License Management API.

After a code has been redeemed, it cannot be used anymore.

Limitations

• Activation code-based licensing is only supported with preconfigured products.

• The maximum batch size is 1000 activation codes.

Before you start

• Make sure you have created the products and product configurations needed.

• It’s important to be aware that after issuing licenses, most of the information in the licenses is fixed and cannot be edited. If, for example, your products or features change and the changes also need to apply to existing licenses, you will need to revoke licenses and issue new licenses as needed.

Step 1: Enable redeeming of activation codes for issuing licenses

Enable end users to redeem activation codes, which triggers the licenses to be issued. This includes implementing a UI (such as a web page) where end users can redeem the codes.

The process differs a bit depending on whether you’re generating license keys for consuming the licenses or using identity-based licensing.

• When a license key is generated and returned for the issued license, choose how to provide the license key to the end user and whether they’re required to enter the license key when using the application (only on first use or every time they access it).

  One option for handling this is that your application stores the license key and uses it from there, and the end user can view the license key in the application UI if needed.

  We also recommend that the end user is able to find the license key, for example, on a customer portal. This is needed to recover from computer failures or other reasons why the key stored in the application might be lost.

  With a license key, the end user can start consuming the license right away.

• If you’re using identity-based licensing, start by onboarding the customer user.

  After this, the user can log in and redeem the activation code.

In the UI that you provide for redeeming activation codes, you can also display information on the license that was issued. In the case of identity-based licensing, you can also allow the user to view information on other licenses they may have access to.

Use the following License Management API operations:

Issued licenses are stored in the customer’s default license container. They can be later moved to another license container if needed.

Step 2: Generate activation codes

Implement the generation of activation codes. You can generate activation codes in batches and individually as needed.

The API uses a “product access grant” entity (ProductAccessGrant) to hold the information on a single activation code.

Choose the batch size

When you’re generating and managing activation codes in batches, your business case that requires activation codes likely also defines other rules that relate to how batches of activation codes are stored, managed, and used in your supply chain.

Let’s take an example case: a calculator manufacturer that offers a license to a desktop or web application with a purchased device. When deciding how to manage activation code batches, our example manufacturer wants to align the generation of activation codes with the production of devices they ship to stores. They’re also taking into account a device’s end-of-life (EOL) and the possibility of stolen goods, which can cause a need to revoke even a whole batch of activation codes.

The maximum batch size is 1000 activation codes.

When choosing your batch size, consider the following:

• In general, we recommend that you match the activation code batch sizes to your production batch sizes. This makes it easier to manage activation codes, for example, if you need to revoke a whole batch of activation codes.

• The bigger your activation code batches get, the bigger the effect that changes have over a large amount of activation codes. With smaller batches you get more granularity, but also potentially more repetitive management work.

It’s still possible to handle activation codes individually when needed, for example, delete an individual code or set it as expired.

Generate a batch of activation codes

Use the following License Management API operations to first generate the batch and then retrieve the generated activation codes.

You can associate external identifiers to batches for integration purposes to map them to records in other systems.

Generate an activation code

Use the following License Management API operation:

Step 3: Distribute activation codes

You can deliver the generated activation codes to your customers in a number of ways. The code can be placed in a physical box, it can be emailed, displayed on a web page, or shown in the application that needs the license, and so on.

You can make changes to activation codes even after distributing them, up until they have been redeemed.

Step 4: Track status of activation codes

After generating and distributing activation codes, you can track how they have been used.

You can, for example, retrieve valid activation codes that are still unredeemed, or activation codes that were redeemed during a certain period of time.

Or, you can retrieve the status of a batch to get the ratio of redeemed activation codes to the batch size, which helps to get an overview of the utilization so far.

Use the following License Management API operations:

Maintenance

You can make changes to activation codes by batch or individually until they have been redeemed.

You cannot change the code part (the unique character string) after the activation code has been generated, but you can make changes to the licensing information behind it. For example, you can change the product configuration used for issuing the license, change the license validity or the quantity granted, or set an activation code as expired.

Redeemed activation codes can no longer be used for anything. You cannot make changes to them, which means updating a batch only affects the unredeemed activation codes in that batch. You can delete unredeemed activation codes if needed.

Updating a batch also doesn’t affect any licenses that have already been issued using activation codes from that batch. For example, if you change the license validity settings for a batch, this doesn’t affect the validity of any existing licenses.

Note: If you make changes to the product configurations that you’re using in activation codes, the changes also apply to licenses that will be issued using activation codes which you have already generated but which haven’t been redeemed yet. You can update the activation codes to use a different product configuration if needed.

Do not delete product configurations used by activation codes while the codes must be usable. Deleting a product configuration automatically deletes any activation codes that use it.

Manage batches of activation codes

Use the following License Management API operations:

Manage individual activation codes

Use the following License Management API operations: