API Documentation

Learn how to integrate the license registration and validation API endpoint into your client applications.

Base URL

http://localhost:9003/api

Validation Basis

Supports Activation-based or Purchase-based checks.

Idempotent Acts

Repeat registration check from the same machine is safe.

POST/issueServer-to-server

Issues (or renews) a yearly, email-locked license after a completed payment. Call this from your payment backend or webhook handler — never from the client app. Requires the x-api-key header (set via the LICENSE_MATE_API_KEY environment variable).

Request Parameters

email(Required)

Buyer email. The issued license key is locked to this email.

string
productId(Required)

The unique product identifier, e.g. PROD-XXXX.

string
txnId(Required)

Unique payment transaction ID. One payment = one license: retries with the same txnId return the same key, and a new txnId for an existing email + product renews the license for another year.

string
expirationBasis(Optional)

'purchase' (default — the year starts now) or 'activation' (the year starts at first device registration).

string

Example (from your payment webhook)

# Call from your payment backend (webhook) AFTER payment succeeds.
# Never call this from the client app - the x-api-key must stay secret.
curl -X POST http://localhost:9003/api/issue \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LICENSE_MATE_API_KEY" \
  -d '{
    "email": "buyer@example.com",
    "productId": "PROD-XXXX",
    "txnId": "payment-transaction-id"
  }'
# => { "success": true, "licenseKey": "XXXXX-XXXXX-...", "expiresAt": "..." }
# Same txnId again  -> same key (safe for webhook retries)
# New txnId, same email+product -> renews the existing key for one more year
POST/register

Register a machine or validate an existing license registration.

Request Parameters

productKey(Required)

The license key to activate.

string
machineId(Required)

Unique hardware ID identifying the machine.

string
email(Required for email-locked licenses)

The buyer email the license is locked to. Must match the email used at purchase. Alternatively, customerId (e.g. CID-XXXXXX) can identify the customer, but the email check still applies when the license has one on file.

string
productId(Required)

The unique product identifier key, e.g. PROD-TEST.

string

Response Behaviors

200 OK (Registration Succeeded / Verified)

Returned for a fresh registration under limits, or if validating an already registered machine (idempotent validation).

403 Forbidden (Limit Exceeded)

Returned when the allowed license count threshold has been fully saturated for this key.

Code Implementation
curl -X POST http://localhost:9003/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "productKey": "KEY-XXXX-XXXX",
    "machineId": "unique-machine-id-123",
    "email": "buyer@example.com",
    "productId": "PROD-XXXX"
  }'