Validating License Keys With the License API
In this tutorial, we’ll go through the full process of creating, verifying and removing license keys for your customers using Lemon Squeezy’s API.
About license keys
License keys are a feature in Lemon Squeezy, which lets you control access to your external application via orders and subscriptions.
Enabling license keys
You can turn on license keys at a product and variant level in Lemon Squeezy.
You have options for length of license and how many activations are allowed for each license.
If your product is a subscription, the “License length” field is not shown in the product form because the length of the license is instead tied to the subscription’s lifecycle. When a subscription becomes expired, the related license key’s status will automatically become expired.
Each time a customer purchases a product with license keys enabled, a license key will be generated and emailed to the customer in their receipt. The customer will also find the license key via the My Orders page.
Each license key can have one or many license key instances, which are created every time you activate the license key. You can deactivate each instance individually as well as disable the license key altogether.
Managing license keys
Once you have customers with license keys, you can easily manage them from Store » Licenses.
On that page you can view all license keys and edit their activation limits and expiration dates. You can also disable and regenerate keys.
License key statuses
When accessing license keys with the API, you’ll see a status value which you can use to determine if a customer should have access to your application.
status will be be one of:
inactive- The license key is valid but has no activations.active- The license key has one or more activations.expired- The license key’s expiry date has passed, either because the related product had a defined license length or because the license’s subscription has expired.disabled- The license key has been manually disabled from the Lemon Squeezy dashboard.
Activating a license key
After a customer has purchased your product, you will need to prompt the user to input their license key into your app so they can gain access to your app. For example, you could create a simple form like this:
Once submitted, you will need to verify the active user somehow. We recommend checking against their email address. To do this you could add an email input into your form, asking the customer to input the email address they used at checkout, then check that when activating the key (see below).
When the user provides their license key you should activate it using the Lemon Squeezy API:
curl -X POST https://api.lemonsqueezy.com/v1/licenses/activate \
-H "Accept: application/json" \
-d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
-d "instance_name=Test"Make sure to replace {LICENSE_KEY} with the license key the user has provided. The instance_name parameter is required and it will be used to give the license key instance a name in your Lemon Squeezy dashboard.
A successful response will look like this:
{
"activated": true,
"error": null,
"license_key": {
"id": 1,
"status": "active",
"key": "38b1460a-5104-4067-a91d-77b872934d51",
"activation_limit": 1,
"activation_usage": 5,
"created_at": "2021-03-25 11:10:18",
"expires_at": null
},
"instance": {
"id": "47596ad9-a811-4ebf-ac8a-03fc7b6d2a17",
"name": "Test",
"created_at": "2021-04-06 14:08:46"
},
"meta": {
"store_id": 1,
"order_id": 2,
"order_item_id": 3,
"product_id": 4,
"product_name": "Example Product",
"variant_id": 5,
"variant_name": "Default",
"customer_id": 6,
"customer_name": "John Doe",
"customer_email": "[email protected]"
}
}In the response you can see details about the license_key, instance and the order, product and customer in meta.
The activated value shows whether the license key has been successfully activated (true) or not (false).
A new license key instance is created for each successful activation request, each with a unique ID (an instance is a recorded “use” of a license key). Make sure you save the instance.id value into your app as you will need this to validate and deactivate license key instances.
You should verify that the store_id, product_id and/or variant_id from this response match the IDs of your Lemon Squeezy product. If you don’t do this, someone using a license key from another Lemon Squeezy product could use it to get access to your product. We recommend hard-coding the store_id, product_id and/or variant_id into your client and using them to validate that the key belongs to your product.
You can also verify that the customer inputting the license key in your app is the same customer who purchased it by checking against meta.customer_email in the response. If the email address matches, you can give access to the user.
If you limited activations when creating the product, you are able to check how many activations have occured from license_key.activation_usage.
Lemon Squeezy will not allow new license key activations once the activation limit has been reached.
Checking the validity of a license key
Now that you have active license keys working in your app, you should periodically check if a license key is still valid. That can be done with the Lemon Squeezy API.
curl -X POST https://api.lemonsqueezy.com/v1/licenses/validate \
-H "Accept: application/json" \
-d "license_key=38b1460a-5104-4067-a91d-77b872934d51"An example response will look like this:
{
"valid": true,
"error": null,
"license_key": {
"id": 1,
"status": "active",
"key": "38b1460a-5104-4067-a91d-77b872934d51",
"activation_limit": 1,
"activation_usage": 5,
"created_at": "2023-03-25 11:10:18",
"expires_at": "2024-03-25 11:10:18"
},
"instance": null,
"meta": {
"store_id": 1,
"order_id": 2,
"order_item_id": 3,
"product_id": 4,
"product_name": "Example Product",
"variant_id": 5,
"variant_name": "Default",
"customer_id": 6,
"customer_name": "John Doe",
"customer_email": "[email protected]"
}
}The valid value will show if the license key is valid or not.
Similarly to above, you can verify that the key is being used for the right user by checking against meta.customer_email.
Validating a license key instance
You can also use the same endpoint to validate a specific license key instance. Just add an instance_id into the request like this:
curl -X POST https://api.lemonsqueezy.com/v1/licenses/validate \
-H "Accept: application/json" \
-d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
-d "instance_id=47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"The response will include an instance object and the valid value will reflect the validity of the instance rather than the license key itself.
{
"valid": true,
"error": null,
"license_key": {
"id": 1,
"status": "active",
"key": "38b1460a-5104-4067-a91d-77b872934d51",
"activation_limit": 1,
"activation_usage": 5,
"created_at": "2021-03-25 11:10:18",
"expires_at": "2022-03-25 11:10:18"
},
"instance": {
"id": "47596ad9-a811-4ebf-ac8a-03fc7b6d2a17",
"name": "Test",
"created_at": "2021-04-06 14:08:46"
},
"meta": {
"store_id": 1,
"order_id": 2,
"order_item_id": 3,
"product_id": 4,
"product_name": "Example Product",
"variant_id": 5,
"variant_name": "Default",
"customer_id": 6,
"customer_name": "John Doe",
"customer_email": "[email protected]"
}
}Deactivating a license key instance
This will only deactivate the specific license key instance, not the license key itself.
You can easily deactivate a specific license key instance using the following request. Deactivating a license will delete the instance and reduce the activation_usage for the license key.
curl -X POST https://api.lemonsqueezy.com/v1/licenses/deactivate \
-H "Accept: application/json" \
-d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
-d "instance_id=f90ec370-fd83-46a5-8bbd-44a241e78665"The response will look like this:
{
"deactivated": true,
"error": null,
"license_key": {
"id": 1,
"status": "active",
"key": "38b1460a-5104-4067-a91d-77b872934d51",
"activation_limit": 5,
"activation_usage": 0,
"created_at": "2021-03-25 11:10:18",
"expires_at": null
},
"meta": {
"store_id": 1,
"order_id": 2,
"order_item_id": 3,
"product_id": 4,
"product_name": "Example Product",
"variant_id": 5,
"variant_name": "Default",
"customer_id": 6,
"customer_name": "John Doe",
"customer_email": "[email protected]"
}
}Note that there is no instance object in the response because it has been deleted.
The underlying license key may still be active, as this endpoint deactivates license key instances rather than the key itself (read on to find out how to disable license keys).
Disabling a license key
It’s not currently possible to disable license keys using the API.
If you want to disable a license key (i.e. fully stop a customer from having access to your product), you can do this from your Lemon Squeezy dashboard.
Go to Store » Licenses and click on the ... menu icon on the license you want to disable. Click on the “Disable key” option and confirm.
That’s it! You now know how to manage license keys for your customers using Lemon Squeezy’s API.
Looking for SDKs?
Lemon Squeezy offers official SDKs for several programming languages to make API integration even easier. Check out our available SDKs to find one that suits your development needs.