User-locked Licenses

What is a user-locked license?

Similar to a node-locked license, a user-locked license is a license that is only allowed to be used by a particluar set of users, typically identified by an email address.

How do I implement a user-locked license?

To configure a user-locked license model, you will want to create a new Policy resource (or modify an existing Policy), and set it to require a user scope. This will ensure that all license validations include the user, in addition to the license's key, otherwise the validation will fail.

After that, you should create a User object for the user you wish to attach to the license. The only required attribute on a User is their email, but there is room for them to add a password and their name as well, in addition to a metadata field, which can be used to store other required information.

Once you've created a User profile, you can generate a new License object (or update an existing one), and set its owner relationship to the previously created User, or attach the user to the license's users relationship. The latter is useful if you have a multi-user licensing model.

Then, within your software, you will want to integrate the following request flow:

1. Validate the license key along with a user validation scope, typically the end-user's email address (but the user's ID can also be provided, instead.)
2. Assert the validation code does not equal USER_SCOPE_REQUIRED or USER_SCOPE_MISMATCH, indicating a user mismatch.

An example of such a validation request would look like this:

curl -X POST https://api.keygen.sh/v1/accounts/demo/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": {
            "user": "[email protected]"
          }
        }
      }'
curl -X POST https://api.keygen.sh/v1/accounts/demo/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": {
            "user": "user@keygen.example"
          }
        }
      }'
content_copy

To ensure that every license validation request is scoped to a user, you can configure your Policy to require a user scope.

Offline capability

By utilizing cryptographically signed license keys, you can implement an offline-capable user-locked licensing model. For example, you could embed the user's email address inside of the license key. Cryptographic license keys can be distributed to air-gapped environments in a variety of ways: email, a license file, USB dongle, on-premise license proxy, or through the use of QR codes.