KeyForge

Claims and activates a software license seat for a specific client workstation. If the key is valid, active, and capacity is available (current_activations < max_activations), the server returns an APPROVED response and atomically consumes a seat.

Request Body Parameters (JSON)

Integration Code Examples

// Frontend Web Application (Browser / React / Vue / Vanilla JS)
async function activateLicense(activationCode) {
  const API_URL = 'https://activation.hudsmersolutions.com/api/v1/activate';

  // Minimal Payload: Only 'code' is strictly required!
  // 'toolName' is optional: identifies this web tool in your multi-tool suite
  // 'deviceId' is optional in frontend: server automatically binds to the user's physical device IP!
  const payload = {
    code: activationCode.trim().toUpperCase(),
    toolName: 'Web Suite Editor' // Optional label for this tool
  };

  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    const result = await response.json();

    if (response.ok && result.status === 'APPROVED') {
      console.log('✅ License Activated on this device:', result.data);
      // Save license code locally in browser storage
      localStorage.setItem('app_license_code', result.data.code);
      localStorage.setItem('app_license_status', 'active');
      return { success: true, data: result.data };
    } else {
      console.error('❌ Disapproved:', result.message);
      alert(result.message || 'Activation rejected. This code may be locked to another device.');
      return { success: false, error: result.error, message: result.message };
    }
  } catch (err) {
    console.error('Network error during activation:', err);
    return { success: false, message: 'Server unreachable: ' + err.message };
  }
}

curl -X POST "https://activation.hudsmersolutions.com/api/v1/activate" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "PRO-8732-K9X1-V74B",
    "toolName": "Web Tool A"
  }'

import requests

API_URL = "https://activation.hudsmersolutions.com/api/v1/activate"

payload = {
    "code": "PRO-8732-K9X1-V74B",
    "deviceId": "station-uuid-9842-acme",
    "deviceName": "Alice Workstation M2"
}

response = requests.post(API_URL, json=payload, timeout=10)
data = response.json()

if response.status_code == 200 and data.get("status") == "APPROVED":
    print("License Approved!")
    print(f"Product: {data['data']['productName']}")
    print(f"Remaining Seats: {data['data']['remainingActivations']}")
    print(f"Expires: {data['data']['expiresAt'] or 'Perpetual'}")
else:
    print(f"Activation Disapproved: {data.get('message')}")
    print(f"Error Code: {data.get('error')}")

async function activateClientLicense(licenseKey, machineId) {
  const url = 'https://activation.hudsmersolutions.com/api/v1/activate';
  
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      code: licenseKey,
      deviceId: machineId,
      deviceName: 'Client Application'
    })
  });

  const resData = await response.json();

  if (response.ok && resData.status === 'APPROVED') {
    console.log('Activation approved:', resData.data);
    // Store activation state locally
    return { success: true, license: resData.data };
  } else {
    console.error('Activation disapproved:', resData.message, resData.error);
    return { success: false, error: resData.error, message: resData.message };
  }
}

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class LicenseManager
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task ActivateAsync(string activationCode, string deviceId)
    {
        var payload = new {
            code = activationCode,
            deviceId = deviceId,
            deviceName = Environment.MachineName
        };

        var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
        var response = await client.PostAsync("https://activation.hudsmersolutions.com/api/v1/activate", content);
        var jsonResponse = await response.Content.ReadAsStringAsync();

        using var doc = JsonDocument.Parse(jsonResponse);
        var root = doc.RootElement;

        if (response.IsSuccessStatusCode && root.GetProperty("status").GetString() == "APPROVED")
        {
            Console.WriteLine("License Approved!");
            return true;
        }

        Console.WriteLine($"Disapproved: {root.GetProperty("message").GetString()}");
        return false;
    }
}

<?php
$url = "https://activation.hudsmersolutions.com/api/v1/activate";
$data = [
    "code" => "PRO-8732-K9X1-V74B",
    "deviceId" => "server-machine-id-01",
    "deviceName" => "Production App Server"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
if ($httpCode === 200 && ($result['status'] ?? '') === 'APPROVED') {
    echo "Activation Approved: Remaining seats: " . $result['data']['remainingActivations'] . "\n";
} else {
    echo "Activation Failed: " . ($result['message'] ?? 'Unknown error') . "\n";
}

Sample Responses

{
  "success": true,
  "status": "APPROVED",
  "message": "Activation successful! Your activation code has been approved.",
  "data": {
    "code": "PRO-8732-K9X1-V74B",
    "clientName": "Acme Studio Inc.",
    "productName": "Studio Pro Suite 2026",
    "deviceId": "station-uuid-9842-acme",
    "deviceName": "Alice Workstation M2",
    "currentActivations": 2,
    "maxActivations": 3,
    "remainingActivations": 1,
    "expiresAt": "2027-12-31T23:59:59.000Z",
    "activatedAt": "2026-10-01T04:45:00.000Z"
  }
}

{
  "success": false,
  "status": "DISAPPROVED",
  "error": "ACTIVATION_LIMIT_EXCEEDED",
  "message": "Maximum number of activations (3) reached for this code. No activations remaining.",
  "currentActivations": 3,
  "maxActivations": 3,
  "remainingActivations": 0
}

Silently verifies license validity without consuming any seats. Ideal for application startup checks or scheduled daily heartbeats.

Request Body Parameters (JSON)

curl -X POST "https://activation.hudsmersolutions.com/api/v1/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "PRO-8732-K9X1-V74B",
    "deviceId": "station-uuid-9842-acme"
  }'

{
  "success": true,
  "status": "APPROVED",
  "message": "Activation code is valid and active.",
  "data": {
    "code": "PRO-8732-K9X1-V74B",
    "clientName": "Acme Studio Inc.",
    "productName": "Studio Pro Suite 2026",
    "isDeviceBound": true,
    "currentActivations": 2,
    "maxActivations": 3,
    "remainingActivations": 1,
    "expiresAt": "2027-12-31T23:59:59.000Z"
  }
}

Releases an active seat from a machine, decrementing current_activations and returning the seat to the available license pool. Essential for machine migrations, uninstalls, and license transfers.

Request Body Parameters (JSON)

curl -X POST "https://activation.hudsmersolutions.com/api/v1/deactivate" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "PRO-8732-K9X1-V74B",
    "deviceId": "station-uuid-9842-acme"
  }'

{
  "success": true,
  "status": "APPROVED",
  "message": "Device deactivated successfully. Activation seat has been released.",
  "data": {
    "code": "PRO-8732-K9X1-V74B",
    "deviceId": "station-uuid-9842-acme",
    "currentActivations": 1,
    "maxActivations": 3,
    "remainingActivations": 2
  }
}

Dual-purpose endpoint: performs public uptime liveness checks with authoritative live UTC timestamps, and functions as a 5-minute periodic heartbeat for client applications to verify license expiration dates and times against verified network UTC—neutralizing client machine clock tampering.

Query / Body Parameters (Optional)

Usage Example 1: Standard Uptime Probe (No Key)

curl "https://activation.hudsmersolutions.com/api/v1/health"

// Response (HTTP 200):
{
  "status": "UP",
  "service": "Activation Code Service API",
  "serverTimeUtc": "2026-10-06T11:42:00.123Z",
  "serverTimestamp": 1791286920123,
  "timezone": "UTC"
}

Usage Example 2: 5-Minute Heartbeat & Live UTC Expiration Check

curl "https://activation.hudsmersolutions.com/api/v1/health?code=PRO-8732-K9X1-V74B&deviceId=dev-workstation-01"

// Response (HTTP 200):
{
  "status": "UP",
  "service": "Activation Code Service API",
  "serverTimeUtc": "2026-10-06T11:42:00.123Z",
  "serverTimestamp": 1791286920123,
  "timezone": "UTC",
  "license": {
    "code": "PRO-8732-K9X1-V74B",
    "valid": true,
    "status": "ACTIVE",        // "ACTIVE", "EXPIRING_SOON", "EXPIRED", or "DEACTIVATED"
    "isExpired": false,
    "isExpiringSoon": false,
    "isPerpetual": false,
    "expiresAt": "2026-10-15T23:59:59.000Z",
    "serverTimeUtc": "2026-10-06T11:42:00.123Z",
    "timeRemaining": {
      "days": 9,
      "hours": 12,
      "minutes": 17,
      "seconds": 58,
      "totalSeconds": 821878
    },
    "productName": "Studio Pro Suite 2026",
    "clientName": "Acme Studio Inc.",
    "maxActivations": 3,
    "currentActivations": 1,
    "remainingActivations": 2,
    "message": "License is active. Expires in 9 days (2026-10-15T23:59:59.000Z UTC).",
    "device": {
      "deviceId": "dev-workstation-01",
      "deviceName": "MacBook Pro Workstation",
      "isRegistered": true,
      "isActive": true,
      "message": "Heartbeat registered: Device active."
    }
  }
}

Programmatically generates single or batch activation license codes. Built for integration with external payment gateways, webhooks (e.g. Stripe, Shopify, WooCommerce), or backend microservices.

Request Body Parameters (JSON)

Integration Code Examples

curl -X POST "https://activation.hudsmersolutions.com/api/v1/codes" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_DEVELOPER_API_KEY" \
  -d '{
    "prefix": "PRO",
    "count": 1,
    "maxActivations": 3,
    "clientName": "Acme Studio Inc.",
    "productName": "Studio Pro 2026",
    "notes": "Automated order fulfillment #8942"
  }'

import fetch from 'node-fetch';

async function provisionLicense(customerEmail, productTier) {
  const response = await fetch('https://activation.hudsmersolutions.com/api/v1/codes', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.KEYFORGE_API_KEY}`
    },
    body: JSON.stringify({
      prefix: 'PRO',
      count: 1,
      maxActivations: 1,
      clientName: customerEmail,
      productName: productTier,
      notes: 'Provisioned via webhook'
    })
  });

  const data = await response.json();
  if (response.ok && data.success) {
    const newLicense = data.data[0];
    console.log('License Key Generated:', newLicense.code);
    return newLicense.code;
  } else {
    throw new Error(data.message || 'License generation failed');
  }
}

import requests

API_URL = "https://activation.hudsmersolutions.com/api/v1/codes"
API_KEY = "kf_live_your_secret_api_key"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

payload = {
    "prefix": "PRO",
    "count": 1,
    "maxActivations": 2,
    "clientName": "alice@example.com",
    "productName": "Studio Pro 2026",
    "notes": "Stripe Checkout session ch_3Nk810..."
}

response = requests.post(API_URL, json=payload, headers=headers)
data = response.json()

if response.status_code == 201 and data.get("success"):
    created_code = data["data"][0]["code"]
    print(f"Generated License Code: {created_code}")
else:
    print(f"Error: {data.get('message')}")

Sample Response

{
  "success": true,
  "message": "Successfully created 1 activation code(s).",
  "data": [
    {
      "id": 14,
      "code": "PRO-8732-K9X1-V74B",
      "status": "active",
      "max_activations": 2,
      "current_activations": 0,
      "client_name": "alice@example.com",
      "product_name": "Studio Pro 2026",
      "expires_at": null,
      "notes": "Stripe Checkout session ch_3Nk810...",
      "created_at": "2026-10-01T05:40:00.000Z"
    }
  ]
}

Standard Error Code Matrix

When a request cannot be fulfilled, the server returns "status": "DISAPPROVED" along with an explicit error code string.

Client Integration Best Practices

• Stable Machine Fingerprint: Generate the deviceId from hardware attributes (e.g. BIOS serial or OS installation UUID) rather than transient items like IP addresses.
• Local State Caching: After a successful /activate call, cache the license token and expiry date in encrypted client storage.
• Silent Background Verification: On app launch, use /api/v1/verify in the background to ensure the license hasn't been revoked, without consuming extra seats.
• Offline Grace Period: If the user's internet is temporarily down, allow a configurable grace period (e.g., 3-7 days) using the cached verification timestamp before disabling software features.