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

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.

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"
        }
      }'
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"
        }
      }'
content_copy

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 authentication. We recommend using the license's key via license authentication. Alternatively, you can use a license token, or a token which belongs to one the user who owns the license.

If you're validating licenses server-side, then using an admin, product, or environment token also works just as well.

The response of the validation request will be a meta object containing the result of the validation: a meta.valid boolean, a meta.code 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: License <key>' \
  -d '{
        "meta": {
          "nonce": 1574265297,
          "scope": {
            "fingerprint": "f1adc3aed0ba31a418fc7c2e1d63c3e0b1207a6cea5613f650945235f1812fcd"
          }
        }
      }'
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: License <key>' \
  -d '{
        "meta": {
          "nonce": 1574265297,
          "scope": {
            "fingerprint": "f1adc3aed0ba31a418fc7c2e1d63c3e0b1207a6cea5613f650945235f1812fcd"
          }
        }
      }'
content_copy

If you don't have the license's ID, the license's key can be used in its place.

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.code 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!