Validating Licenses

Use Keygen's API and your code to validate licenses for your product. If you need help after reading this, can reach out to us anytime at [email protected].


License key validation flow

Diagram of validating a license key


Validate by license key

If you would like to validate a license by key, you can use the validate-key action. Validating a license key does not require an API authentication token, unlike validating by a license ID.

Did you know that you can require a machine fingerprint during a license validation request? This is incredibly useful when implementing licensing models which require tracking machine usage, e.g. a node-locked model or a floating license model. You can enable "require fingerprint scope" on the license policy.

The response of the validation request will be a meta object containing the result of the validation: a meta.valid boolean, and a meta.detail human-readable description of the validation result. The full license object will also be included in the response body.

curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/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"
}
}'

View the key validation action in the API reference


Validate by license ID

To validate a license directly by it's ID, send a POST request to the license's validate action. Validating a license by ID requires an authentication token. We recommend using an activation token, or a token which belongs to one of your users. But if you're validating licenses server-side, then using an admin or product token also works just as well.

You can provide additional information for license validations using meta.scope. This is useful for providing things such as a machine fingerprint for certain licensing models.

The response of the validation request will be a meta object containing the result of the validation: a meta.valid boolean, a meta.constant machine-readable constant, and a meta.detail human-readable description of the validation result. The full license object will also be included in the response body.

curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"meta": {
"nonce": 1574265297,
"scope": {
"fingerprint": "f1adc3aed0ba31a418fc7c2e1d63c3e0b1207a6cea5613f650945235f1812fcd"
}
}
}'

View the validation action in the API reference


Handling failures

Depending on your product and business requirements, you may want to implement additional logic when, for example, your user does not have an active internet connection, or their license fails validation for some reason or another. Below are a few license validation failure scenarios:

Validation request was successful, but license is not valid

License validation failures are innevitable, and how you handle them will differ based on your business requirements. Here are a few ideas for handling such a situation:

  1. Immediately show a dialog detailing the validation failure (you can find out the reason using the meta.constant key within the validation response).
  2. Depending on how you're licensing your product (e.g. user profiles with associated licenses vs. only license keys), you can prompt the user to purchase a new license, resolve the invalid license, etc.
  3. When a license is expired, rather than immediately exiting your application, consider prompting the user to purchase a subscription renewal or perhaps even up-sell them.

Alternatively, you could disallow access to the product, or implement a grace period while prompting the user to resolve the validation failure—though ideally, this should be communicated beforehand by listening for upcoming license expiration and overdue check-in events so that the potential for validation failures i.e. license churn is diminished.

Useful webhooks for this purpose are:

  • license.expiring-soon (webhook event sent 3 days, 2 days, and 1 day before expiration)
  • license.expired
  • license.check-in-required-soon (sent 3 days, 2 days, and 1 day before due date)
  • license.check-in-overdue

Validation request failed e.g. timeout

The failure could be for a number of reasons, but the most likely culprit is that your user doesn't have an active internet connection. You could handle this type of failure in a variety of ways, but here are a few ideas:

  1. Begin a grace period (e.g. 30 days or 5 additional product usages), where you disallow access to the product if a license validation has not been successful after that timeframe. You should clearly tell your users that they should connect to the internet when possible and be upfront about the grace period.
  2. Fallback to offline license key validation if you're utilizing cryptographically signed or encrypted license keys (see the API reference for more information).
  3. Immediately disallow access to the product. This should be used with care, and is not recommended unless your product relies on an active internet connection.

Example applications

Below you can find example applications detailing license validation in various programming languages. These may be a great place to start.


Next steps

Congrats! You've validated your first license using Keygen. Next up you could start activating machines for your users' licenses, to get a better understanding of how your users operate and where they use your product, and to limit cross-device usage.

If you have any questions about what you've learned today, be sure to reach out!