To use UUIDs to identify the end user and lock a license key to their device your app must first generate the UUID (see our full documentation on generating UUIDs in various ways). Your app must generate the UUID to ensure it is locally unique to their device and also that it is securely locked away locally.
If your app is a piece of software (such as a video game or software app) that installs on a PC running a Windows, Mac, or Linux operating system , it should send the following data to the API:
- License key
- Your unique API Auth Key (shown in your Dashboard)
- UUID
In this section we discuss how to send the UUID for checking. Before we get into how to do this let’s explain the feature in detail.
UUID Locks #
UUIDs are used to uniquely identify an installation of your app. Keys intended for use on a PC are UUID locked to prevent unauthorized use of your keys. Without a UUID lock, an end user could install your app on an unlimited amount of devices with a single key.
If allowing end users to install your app on unlimited devices is your intended purpose you still must send the UUID to the API for the license key check to validate. By setting the maximum amount of UUIDs a key can be used on to 0 (unlimited) the key can still be used on any UUIDs.
NOTE: You must send a UUID (or domain for web installed apps) or the key will not validate.
Available Options #
A key can be locked to the initial UUID that sent the key or set to allow X amount of UUIDs. For example, you could sell your app in three tiers that allows it to be installed on a single device for the silver plan, three devices for the gold plan, and unlimited devices for the platinum plan. It’s an easy way to increase the value of your product with minimum effort.
The amount of UUIDs a key is locked to can be any amount and is up to you. It is set during key generation and can also be changed later in the Dashboard.
Setting the amount of UUIDs a key can be used on to 0 marks it for unlimited use. The key will still record the UUIDs it is installed on, but it will not restrict the key based on devices.
For information on how to make these changes in the Dashboard, as well as edit the actual UUIDs, see our full documentation on the Dashboard.
NOTE: If a previously used unlimited key is later set to UUID lock based on the number of UUIDs, ensure this number matches or is larger than the amount of UUIDs already saved to that key.
How UUID Locking Is Checked #
Initial Key Checks: During the initial key check the API will save the UUID along with the key and associate the two.
Subsequent Key Checks On Same Device: Whenever your app rechecks a key the API will compare the requesting UUID to the recorded UUIDs and either pass as valid if a match is found or fail if they do not.
Subsequent Key Checks On Different UUIDs: If an end user installs your app on another device and enters the same key our system will check if that key allows multiple UUIDs, and if the current amount of UUIDs is within the maximum amount of UUIDs allowed (or unlimited UUIDs are allowed). If so, our system will add the new UUID to the key register. If their key only allows one UUID or the maximum amount of UUIDs is already associated with that key it will fail to validate the key check.
This means your users can uninstall and reinstall your app as much as they need without contacting you for a key reset, assuming they always install it back on the same device with the same UUID.
Sending API Calls With A UUID #
Whenever you send an API call be sure to include the UUID inside the request headers. Before checking a UUID your app must first generate the UUID (see our full documentation on generating UUIDs in various ways).
Our API expects a variable “uuid” as part of the request headers. Here below we have an example in Python that grabs the license key from a user-submitted form and calls the API. We then handle the response back from the API.
For simplicity we have generated the UUID inside this script, which is fine. Also, this example assumes it’s a standalone app installed on a Windows PC. For more information, see our documentation on making API calls.
import os
import uuid
import requests
import tkinter as tk
from tkinter import messagebox
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
# Get base URL and auth key from environment variables
base_url = os.getenv('BASE_URL')
auth_key = os.getenv('AUTH_KEY')
def submit_license_key():
license_key = entry.get()
# Generate a UUID (see our documentation for info about generating UUIDs)
uuid_str = str(uuid.uuid4())
headers = {
'auth': auth_key,
'key': license_key,
'uuid': uuid_str
}
response = requests.get(base_url, headers=headers)
messagebox.showinfo("Response", response.text)
# Set up the GUI
root = tk.Tk()
root.title("License Key Checker")
# Create a label and entry widget
label = tk.Label(root, text="Enter your license key:")
label.pack()
entry = tk.Entry(root)
entry.pack()
# Create a submit button
submit_button = tk.Button(root, text="Submit", command=submit_license_key)
submit_button.pack()
# Start the GUI event loop
root.mainloop()