Node-Locking & Machine Identifiers

Bind software license keys to physical hardware and handle stable machine identification across platforms.

Node-locking restricts license key usage to authorized devices. To enforce this control, the client application must generate a stable hardware fingerprint and register it as a host identifier during activation.

Configuration Modes

1. Node-Locked Keys

Pass the allowedHosts parameter (an array of pre-authorized hardware IDs) when issuing a license key. Keymint will reject activations from any device whose hostId is not present in this list.

{
  "productId": "prod_Nx8K2mLpQ4rVtW9sBc",
  "maxActivations": 3,
  "allowedHosts": ["mac-studio-m2", "windows-workstation-9"]
}

2. Floating / Dynamic Keys

Omit allowedHosts. The key can activate on any hardware device up to the maxActivations count limit. Each activation is tracked by its unique hostId.

3. Anonymous Activations

If you omit the hostId during activation, Keymint automatically generates a random device identifier and returns it in metadata.hostId. Your client application must cache this identifier and send it with subsequent verification calls to prevent consuming additional seat slots.

Stable Hardware Fingerprinting

Instead of querying command line utilities or writing custom scripts to resolve system serial numbers, use Keymint's built-in hardware identification methods.

The official Keymint SDKs provide highly resilient fingerprinting logic out-of-the-box. The SDK automatically:

1. Queries the hardware/BIOS UUID (Windows, macOS, Linux).
2. Falls back to OS-level GUIDs and primary network adapter MAC addresses if BIOS access is restricted.
3. Filters out generic or cloned virtual machine strings (e.g. all zeros, all Fs, or standard OEM placeholders) to prevent machine collision bugs.
4. Persists the fingerprint to a secure local file (~/.keymint/installation-id by default) to ensure it remains stable across application restarts, software updates, and minor hardware upgrades.

Use this persistent identifier as the hostId (Machine Code) when checking out or activating keys.

Using the SDK Utilities

import { KeyMint } from 'keymint';

// Generates, persists, and returns a stable machine identifier
const hostId = KeyMint.getOrCreateInstallationId();

console.log(`Machine fingerprint: ${hostId}`);