Developer documentation

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

  1. Create a developer account and choose a plan.
  2. Add your app on the Products page and note its product ID.
  3. Create an API key.
  4. When a customer buys, call generate_license and email them the key.
  5. On first run, call activate and store the activation_token.
  6. 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.

FieldRequiredDescription
product_idYesYour product ID from the Products page.
license_type_idYesID from the License types page. Sets the default activation limit and duration.
customer_emailYesBuyer's email. They can see the license in their free customer account.
customer_nameNoBuyer's name.
order_referenceNoYour order or invoice number (max 50 characters). Customers can use it to recover lost keys.
quantityNoNumber of keys to create. Default 1.
max_activationsNoOverride the license type's device limit.
expires_atNoExpiry date as YYYY-MM-DD. Defaults to the license type's duration, or never.
notesNoPrivate 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.

FieldRequiredDescription
license_keyYesThe key the customer entered.
hardware_idYesA stable identifier for the machine. See best practices.
computer_nameNoShown to you and the customer, e.g. "Office-PC".
os_infoNoe.g. "Windows 11 Pro 23H2".
app_versionNoYour 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.

FieldRequiredDescription
license_keyYesThe license key.
hardware_idRecommendedSame value you sent to activate.
activation_tokenRecommendedToken returned by activate. Send with hardware_id to check this specific installation.
app_versionNoUpdates 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.

FieldRequiredDescription
license_keyYesThe license key.
hardware_idYesThe device being deactivated.
activation_tokenYesThe token from activation.
reasonNoStored 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 happensLicense
Monthly payment succeedsActive, 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 cancelledStays active until the end of the month already paid for, then suspended.
Payment refunded or charged backSuspended straight away.
No payment reported at allThe 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, set subscription_data[metadata][license_key]).
  • PayPal: set the subscription's custom_id to 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.

actionExtra fieldsEffect
paymentreference (your payment ID, recommended - repeats are ignored), optional paid_until (ISO date), amount (smallest unit, e.g. cents), currencyExtends 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.
suspendtype: refunded, chargeback or unpaid; or your own reason textSuspends now.
linkprovider (stripe/paypal), subscription_id, optional customer_idConnects 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 statusWhat it meansWhat to show the customer
Invalid license key formatNot in XXXX-XXXX-XXXX-XXXX format.Ask them to check the key, including hyphens.
License key not foundNo such key.Link to installationkey.com/lookup/ to recover it.
License is not activeYou 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 expiredPast its expiry date.Offer a renewal link.
Maximum number of activations reachedDevice limit used.Ask them to deactivate an old device, or contact you.
Invalid activation token for this hardwareToken doesn't match this device, or the installation was deactivated.Ask them to re-enter their key (call activate again).
HTTP 400Required field missing or invalid JSON.Fix your request.
HTTP 401API key missing, revoked or paused.Check your key and subscription.
HTTP 405Not 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.

Get started