Licensing API integration guide
Everything you need to generate license keys, lock them to a device or domain, and check them from your app. All endpoints accept and return JSON over HTTPS.
Quick start
- Create a developer account and choose a plan.
- Add your app on the Products page and note its product ID.
- Create an API key.
- When a customer buys, call generate_license and email them the key.
- On first run, call activate and store the
activation_token. - On every start-up, call validate with the key, hardware ID and token.
License keys look like A1B2-C3D4-E5F6-7890: four groups of four uppercase letters or numbers.
Authentication
Send your API key in the X-API-Key header with every request, and the body as JSON with Content-Type: application/json.
POST https://www.installationkey.com/api/validate.php
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{ "license_key": "A1B2-C3D4-E5F6-7890" } A missing, revoked or paused key returns HTTP 401 with {"error": "Unauthorized"}. Keys are paused automatically if your subscription ends and resume when you resubscribe.
Generate license keys
POST/api/generate_license.php
Call this from your store, checkout or payment webhook. It's a server-to-server call: never put it in software you ship to customers.
| Field | Required | Description |
|---|---|---|
product_id | Yes | Your product ID from the Products page. |
license_type_id | Yes | ID from the License types page. Sets the default activation limit and duration. |
customer_email | Yes | Buyer's email. They can see the license in their free customer account. |
customer_name | No | Buyer's name. |
order_reference | No | Your order or invoice number (max 50 characters). Customers can use it to recover lost keys. |
quantity | No | Number of keys to create. Default 1. |
max_activations | No | Override the license type's device limit. |
expires_at | No | Expiry date as YYYY-MM-DD. Defaults to the license type's duration, or never. |
notes | No | Private note stored with the license. |
curl -X POST https://www.installationkey.com/api/generate_license.php \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_id": YOUR_PRODUCT_ID,
"license_type_id": 2,
"customer_email": "buyer@example.com",
"customer_name": "Sam Buyer",
"order_reference": "ORDER-10482"
}' Success returns HTTP 201:
{
"success": true,
"message": "1 license(s) generated successfully",
"license_key": "A1B2-C3D4-E5F6-7890",
"license_id": 512,
"licenses": [
{
"license_id": 512,
"license_key": "A1B2-C3D4-E5F6-7890",
"product_name": "Your App Pro",
"license_type": "Standard",
"max_activations": 1,
"expires_at": null,
"customer_email": "buyer@example.com",
"customer_name": "Sam Buyer",
"order_reference": "ORDER-10482"
}
],
"generation_time": "2026-10-05 10:15:00"
} license_key and license_id appear at the top level only when quantity is 1. Missing fields return HTTP 400 with an error message.
Your API key can only create licenses for your own products, using the built-in license types or license types you created. Any other product_id returns HTTP 400 {"error": "Product not found"}, and any other license_type_id returns {"error": "License type not found"}.
Activate a license
POST/api/activate.php
Call this the first time the customer enters their key. It locks the license to the device and uses one activation.
| Field | Required | Description |
|---|---|---|
license_key | Yes | The key the customer entered. |
hardware_id | Yes | A stable identifier for the machine. See best practices. |
computer_name | No | Shown to you and the customer, e.g. "Office-PC". |
os_info | No | e.g. "Windows 11 Pro 23H2". |
app_version | No | Your app's version number. |
curl -X POST https://www.installationkey.com/api/activate.php \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"license_key":"A1B2-C3D4-E5F6-7890","hardware_id":"5f0c9a…","computer_name":"Office-PC","app_version":"2.4.0"}' // Activated
{
"activated": true,
"message": "License activated successfully",
"activation_token": "9f2c4e…64 hex characters…",
"product_name": "Your App Pro",
"license_type": "Standard",
"customer_name": "Sam Buyer",
"expires_at": null
}
// Limit reached
{
"activated": false,
"message": "Maximum number of activations reached",
"current_activations": 1,
"max_activations": 1
} Activating again on the same hardware_id doesn't use another activation; it returns "activated": true with the existing token and the message License already activated for this hardware. Save the activation_token: you need it to validate and deactivate.
Validate on start-up
POST/api/validate.php
Call this each time your app starts (or daily for long-running apps). It confirms the license is still active, not expired, and activated on this device.
| Field | Required | Description |
|---|---|---|
license_key | Yes | The license key. |
hardware_id | Recommended | Same value you sent to activate. |
activation_token | Recommended | Token returned by activate. Send with hardware_id to check this specific installation. |
app_version | No | Updates the version shown in your dashboard. |
// With hardware_id + activation_token
{
"valid": true,
"message": "License is valid and active",
"product_name": "Your App Pro",
"license_type": "Standard",
"customer_name": "Sam Buyer",
"expires_at": null,
"days_since_activation": 42,
"days_since_check_in": 1
}
// Key only (no device check)
{
"valid": true,
"message": "License is valid",
"product_name": "Your App Pro",
"license_type": "Standard",
"customer_name": "Sam Buyer",
"expires_at": null,
"max_activations": 1,
"active_activations": 1,
"status": "active"
}
// Deactivated or expired
{ "valid": false, "message": "License is not active", "status": "revoked" }
{ "valid": false, "message": "License has expired", "status": "expired" } Only send the key without a device check for things like a website "check my license" form. Inside your app, always send hardware_id and activation_token so a copied key can't run on another machine.
Deactivate a device
POST/api/deactivate.php
Frees an activation so the customer can move their license to a new computer. Put a "Deactivate this computer" button in your app's settings.
| Field | Required | Description |
|---|---|---|
license_key | Yes | The license key. |
hardware_id | Yes | The device being deactivated. |
activation_token | Yes | The token from activation. |
reason | No | Stored with the activation. Defaults to "User initiated deactivation". |
{ "deactivated": true, "message": "License deactivated successfully" }
{ "deactivated": false, "message": "No matching active installation found" }
Domain licensing (web apps, scripts and plugins)
For software installed on a website, license by domain name instead of hardware ID. Domain and desktop activations share the same activation limit.
Activate a domain
POST/api/domain_activate.php
Fields: license_key and domain_name (required), plus optional installation_path, server_info and app_version. The domain is stored in lower case. The response matches activate, with the message License activated successfully for domain.
Validate a domain
POST/api/domain_validate.php
Fields: license_key, domain_name and activation_token (all required), plus optional app_version.
{
"valid": true,
"message": "License is valid and activated for this domain",
"product_name": "Your Plugin Pro",
"expires_at": "2027-10-05 00:00:00",
"days_since_activation": 12,
"days_since_check_in": 0,
"next_check_required": "2026-10-12 10:15:00"
} Deactivate a domain
POST/api/domain_deactivate.php
Fields: license_key, domain_name and activation_token (required), plus optional reason. Returns {"deactivated": true, "message": "License successfully deactivated for this domain"}.
All three domain endpoints require your X-API-Key header and only work with licenses for your own products. A missing or invalid key returns HTTP 401 {"error": "Unauthorized"}; a license that isn't yours is reported as License key not found.
Offline activation
POST/api/offline_activate.php
For machines that can't reach the internet, your app shows a request code that the customer submits from another device (for example through your website). Fields: license_key, hardware_id and a unique request_code (required), plus optional computer_name, os_info and app_version.
{
"success": true,
"message": "Offline activation request submitted successfully",
"request_id": 77,
"product_name": "Your App Pro",
"instructions": "Please provide this request code to your system administrator or support team to complete the activation."
} Requests appear under Offline requests in your developer portal. When you approve one, you get an activation code (and can email it to the customer). Your app saves that code as the activation_token for the device, then validates with validate.php using the same hardware_id whenever the machine is online. Approved requests use one of the license's activations.
Subscription licenses (monthly rebilling)
A license issued with a Monthly subscription license type (the built-in Monthly Subscription type, or your own type with Billing set to monthly on License types) stays valid only while the customer keeps paying:
| What happens | License |
|---|---|
| Monthly payment succeeds | Active, paid for another month. A suspended license is reinstated. |
| Payment fails (card declined, no funds) | Stays active for the license type's grace days (default 3) while the payment is retried, then suspended. |
| Subscription cancelled | Stays active until the end of the month already paid for, then suspended. |
| Payment refunded or charged back | Suspended straight away. |
| No payment reported at all | The first month is counted from when the license was issued; after that (plus grace) it is suspended by the hourly check. |
Your app needs no changes. A suspended license is refused by activate, validate and the domain endpoints exactly like a deactivated one, with the message "License is not active". validate.php also returns "status": "suspended", so you can show the customer a "payment needed" message instead of a generic error. The license works again on the next check after they pay.
Option 1: connect Stripe or PayPal (no code)
On Payment integrations, add your webhook URL to your own Stripe or PayPal account. Then put the license key on each customer's subscription:
- Stripe: subscription metadata
license_key=XXXX-XXXX-XXXX-XXXX(with Checkout, setsubscription_data[metadata][license_key]). - PayPal: set the subscription's
custom_idto the license key when you create it.
You can also link a subscription ID to a license by hand on the license's page, or with the link action below.
Option 2: report payments from your own system
POST/api/subscription.php
Send your X-API-Key header and a JSON body with action and license_key. Works with any shop or payment provider.
| action | Extra fields | Effect |
|---|---|---|
payment | reference (your payment ID, recommended - repeats are ignored), optional paid_until (ISO date), amount (smallest unit, e.g. cents), currency | Extends the license a month (or to paid_until) and reinstates it if suspended. |
payment_failed | - | Starts the grace period. |
cancel | - | Suspends when the paid month ends. |
suspend | type: refunded, chargeback or unpaid; or your own reason text | Suspends now. |
link | provider (stripe/paypal), subscription_id, optional customer_id | Connects the license to a subscription for Option 1. |
status | - | Returns the current billing state. |
curl -X POST https://www.installationkey.com/api/subscription.php \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"action":"payment","license_key":"ABCD-1234-EFGH-5678","reference":"order_10293"}' {
"success": true,
"message": "Payment received: license reinstated, paid until 29 Nov 2026",
"license_key": "ABCD-1234-EFGH-5678",
"status": "active",
"valid": true,
"license_type": "Monthly Subscription",
"subscription": true,
"paid_until": "2026-11-29T18:40:00+00:00",
"billing_status": "ok",
"provider": null,
"subscription_id": null,
"last_payment_at": "2026-10-29T18:40:00+00:00",
"reason": null
} Errors: HTTP 401 for a missing or invalid key, 404 {"error": "License not found"} for a key that isn't one of your licenses, 400 if the license isn't a subscription license or a field is missing.
Code examples
C# (.NET 6+)
using System.Net.Http.Json;
using System.Text.Json;
var http = new HttpClient { BaseAddress = new Uri("https://www.installationkey.com/api/") };
http.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
// First run: activate
var act = await http.PostAsJsonAsync("activate.php", new {
license_key = licenseKey,
hardware_id = HardwareId.Get(), // your stable machine fingerprint
computer_name = Environment.MachineName,
os_info = Environment.OSVersion.ToString(),
app_version = "2.4.0"
});
var a = await act.Content.ReadFromJsonAsync<JsonElement>();
if (a.GetProperty("activated").GetBoolean())
Settings.Save(licenseKey, a.GetProperty("activation_token").GetString());
else
MessageBox.Show(a.GetProperty("message").GetString());
// Every start-up: validate
var val = await http.PostAsJsonAsync("validate.php", new {
license_key = Settings.LicenseKey,
hardware_id = HardwareId.Get(),
activation_token = Settings.ActivationToken
});
var v = await val.Content.ReadFromJsonAsync<JsonElement>();
bool licensed = v.GetProperty("valid").GetBoolean();
Python
import requests, uuid, platform
API = "https://www.installationkey.com/api"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
hardware_id = str(uuid.getnode()) # replace with a stronger fingerprint in production
def activate(key):
r = requests.post(f"{API}/activate.php", headers=HEADERS, timeout=15, json={
"license_key": key,
"hardware_id": hardware_id,
"computer_name": platform.node(),
"os_info": platform.platform(),
}).json()
return r.get("activation_token") if r.get("activated") else None
def is_licensed(key, token):
r = requests.post(f"{API}/validate.php", headers=HEADERS, timeout=15, json={
"license_key": key, "hardware_id": hardware_id, "activation_token": token,
}).json()
return r.get("valid", False), r.get("message")
PHP (generate a key from a payment webhook)
$ch = curl_init('https://www.installationkey.com/api/generate_license.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'product_id' => YOUR_PRODUCT_ID,
'license_type_id' => 2,
'customer_email' => $order['email'],
'customer_name' => $order['name'],
'order_reference' => $order['id'],
]),
]);
$result = json_decode(curl_exec($ch), true);
$licenseKey = $result['license_key'] ?? null; // email this to the customer
JavaScript (Node.js 18+ / Electron)
const API = 'https://www.installationkey.com/api';
const headers = { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' };
export async function validate(licenseKey, hardwareId, activationToken) {
const res = await fetch(`${API}/validate.php`, {
method: 'POST',
headers,
body: JSON.stringify({ license_key: licenseKey, hardware_id: hardwareId, activation_token: activationToken }),
});
const data = await res.json();
return { valid: data.valid === true, message: data.message };
}
Messages and errors
Business results (key not found, expired, limit reached) return HTTP 200 with activated/valid/deactivated set to false and a message you can show the customer. Request problems use HTTP status codes.
| Message or status | What it means | What to show the customer |
|---|---|---|
Invalid license key format | Not in XXXX-XXXX-XXXX-XXXX format. | Ask them to check the key, including hyphens. |
License key not found | No such key. | Link to installationkey.com/lookup/ to recover it. |
License is not active | You deactivated the license, or (with "status": "suspended") a subscription payment is missing. | Deactivated: point them to their customer account to see your reason. Suspended: ask them to update their payment; it works again once paid. |
License has expired | Past its expiry date. | Offer a renewal link. |
Maximum number of activations reached | Device limit used. | Ask them to deactivate an old device, or contact you. |
Invalid activation token for this hardware | Token doesn't match this device, or the installation was deactivated. | Ask them to re-enter their key (call activate again). |
HTTP 400 | Required field missing or invalid JSON. | Fix your request. |
HTTP 401 | API key missing, revoked or paused. | Check your key and subscription. |
HTTP 405 | Not a POST request. | Use POST. |
Best practices
- Hardware ID: combine stable values such as the motherboard serial, system drive serial and machine GUID, then hash them (SHA-256). Avoid values that change, like IP address or MAC address on laptops with docking stations.
- Work offline gracefully: cache the last successful validation with a timestamp. If the network is down, allow a grace period (for example 7 days) before asking the customer to reconnect.
- Don't block on timeouts: use a 10-15 second timeout and treat network errors differently from
"valid": false. - One API key per app: keys shipped inside desktop software can be extracted. Separate keys let you rotate one without affecting your other products. Never ship code that calls
generate_license.php. - Let customers move devices: a "Deactivate this computer" button cuts support requests more than anything else.
- Link to self-service: show
https://www.installationkey.com/lookup/next to your license key box so customers can recover lost keys without emailing you.
Ready to integrate?
Create a developer account and make your first activation call today.