menu
 

Feature Licenses

What is a feature license?

A feature license is a license that is entitled to utilize a particular feature of a software application, or many features. For example, an vendor may want to have certain premium features of their software application offers behind a "Pro" license, or a software business may want to limit features for timed trial licenses.

How do I implement a feature license?

By utlizing the entitlements resource, you can define the various features of your application, and attach those entitlements to policies and to licenses. You can then use a couple different methods to assert and check that a license possesses a given entitlement.

Entitlements can be used to manage application features, add-on modules and other types of in-app purchases. Upon purchase, you can attach an entitlement to the license, and upon cancelation you can detach the entitlement.

An entitlement object looks like this:

{
  "data": {
    "id": "db1ff21b-f42f-4623-952b-ca7f2600bded",
    "type": "entitlements",
    "attributes": {
      "name": "Example Feature",
      "code": "EXAMPLE_FEATURE",
      "metadata": {},
      "created": "2021-04-22T17:00:00.000Z",
      "updated": "2021-04-22T17:00:00.000Z"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/1fddcec8-8dd3-4d8d-9b16-215cac0f9b52"
        },
        "data": {
          "type": "accounts",
          "id": "1fddcec8-8dd3-4d8d-9b16-215cac0f9b52"
        }
      }
    },
    "links": {
      "self": "/v1/accounts/1fddcec8-8dd3-4d8d-9b16-215cac0f9b52/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
    }
  }
}

The most important part of an entitlement is the code attribute. These codes can be utilized within your software application to check if a license is entitled to do something. For example, you could have an entitlement with code PRO_FEATURES, then within your software you could list the license's entitlements and do something like this:

const entitlements = await listEntitlementsForLicense(license.id)
if (entitlements.includes('PRO_FEATURES')) {
  await performProFeature()
}

Entitlements can be attached to policies and also to licenses. When an entitlement is attached to a policy, all licenses that 'implement' that particular policy will automatically inherit the policy's entitlements. You can attach one-off entitlements to licenses directly.

For entitlements that are "table-stakes", i.e. required entitlements, you can include those entitlement codes inside of a validation request using the new entitlements scope:

curl -X POST https://api.keygen.sh/v1/accounts/1fddcec8-8dd3-4d8d-9b16-215cac0f9b52/licenses/actions/validate-key \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "meta": {
          "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
          "scope": {
            "entitlements": [
              "RUN_APPLICATION_V1"
            ]
          }
        }
      }'

Entitlements can be utilized to implement robust feature entitlement systems for your software application. In the future we'll be adding additional features such as entitlement meters and usage limits, so please reach out if you have any specific requirements.

View the entitlements resource in the API reference

Entitlements for updates and distribution

Entitlements can also be used with Keygen Dist to manage things such as version entitlements. For example, when you go from v1 to a v2 release of your software, you may not want to let users that didn't upgrade their license to download and use v2 until they purchase an updated license. In this scenario, you would create a APP_V1 entitlement and an APP_V2 entitlement. Then, within your auto-updater code, you'd want to add the entitlement assertion to the update URL:

https://dist.keygen.sh/v1/demo/update/macos/zip/v2.0.0?entitlement=APP_V2

Using metadata to store entitlements

Perhaps one of the easiest ways to configure your licenses to have different feature entitlements is by storing feature toggles in the license's metadata attribute. You can utilize a license's metadata attribute to store any type of key-value data.

For example, a license's metadata may look like this:

{
  "metadata": {
    "basicFeatureX": true,
    "basicFeatureY": true,
    "proFeatureZ": false
  }
}

These feature toggles can be utilized in your application by accessing the license's metadata attribute. The license object will be included in all license validation responses.

A license's metadata attribute can be edited and those changes will immediately be applied to the running application on subsequent license validation requests.

One of the downsides to this approach is keeping the metadata schemas up to date as new features are rolled out. New feature flags will need to be implemented in a backwards compatible way, or backfilled to licenses as needed.

Embedding entitlements into license keys

By utilizing cryptographically signed or encrypted license keys, you can embed tamper-proof feature entitlements within the key itself.

Once a cryptographic license key is created, it cannot be changed. Meaning, the entitlements that you choose to embed into a license key cannot be changed, and changes to the license object itself have no effect on the embedded dataset. If you need to change the embedded entitlements, a new license will need to be created.

Separate licenses per-feature or module

Feature licensing may also be accomplished using multiple licenses per-user, each license implementing a feature policy. For example, you could create a handful of policies, one for each feature or module you offer, and assign licenses implementing those policies to each user, according to their entitlements.

Offline capability

An offline-capable feature licensing model can be implemented in a couple different ways, depending on the method used for storing feature entitlements.

When utilizing cryptographically signed or encrypted license keys, you can decode or decrypt the embedded dataset and verify its authenticity according to the chosen cryptographic scheme. The decoded entitlement values can then be utilized in your software. This method does not require an up-front internet connection, since the cryptographic key can be delivered via email, license file, certificate, or USB key.

When utilizing a license's metadata for feature toggles, license validation data can be cached locally, along with the response signature, for offline use. This method will require an internet connection up-front for the initial validation request.

Perpetual LicenseTimed LicenseFloating LicenseNode‑locked LicenseFeature License
Expiration DateNoYesOptionalOptionalOptional
Activation LimitsOptionalOptional> 01Optional
Feature LimitsOptionalOptionalOptionalOptionalYes
Offline SupportYesYesYesYesYes
Learn MoreLearn MoreLearn MoreLearn More