Activation ties a license key to one computer and returns an instance.id. Validation sends it on every launch. Both run in the main process, so the key never reaches a renderer. This page covers the Electron-specific parts: the machine id, the states the renderer needs, and what a rename or a reinstall does to a seat. The post, save, load and clear helpers are the ones from the validation page.
A fingerprint
The API takes an optional fingerprint of up to 200 characters. With one, activating again from the same computer returns the same seat and updates its name. Without one, every reinstall takes another seat. The node-machine-id package, which has no native dependencies, reads the operating system’s own id. Its README names MachineGuid on Windows, IOPlatformUUID on macOS and the dbus machine-id file on Linux. Hash it with a constant that belongs to your app, so what you send cannot be matched to anything outside it:
import { createHash } from 'node:crypto';
import machineId from 'node-machine-id';
const APP_SALT = 'com.example.inkwell'; // a constant of your own, not app.getName()
export function fingerprint() {
try {
const raw = machineId.machineIdSync({ original: true });
return createHash('sha256').update(`${APP_SALT}:${raw}`).digest('hex');
} catch {
return undefined; // no id available: activate without a fingerprint
}
}
Do not use app.getName() as the salt. Rename the app, and every customer’s fingerprint changes. The call took about 30 ms on a Mac, where it runs a command, so call it at activation and not on a hot path. The result is 64 hex characters.
Activate
Give the renderer a state, not a response. Four outcomes need four different screens:
import { hostname } from 'node:os';
/** { state: 'activated' | 'limit-reached' | 'refused' | 'unavailable', ... } */
export async function activate(base, licenseKey) {
const body = { license_key: licenseKey, instance_name: hostname() };
const fp = fingerprint();
if (fp) body.fingerprint = fp;
const r = await post(base, 'activate', body);
if (!r) return { state: 'unavailable' }; // offline or timeout
const message = r.body.error ?? 'Activation failed.';
if (r.status === 200 && r.body.instance?.id && r.body.token) {
await save({ key: licenseKey, instanceId: r.body.instance.id, token: r.body.token });
return { state: 'activated' };
}
if (r.status === 400 || r.status === 404) {
const lic = r.body.license_key;
if (lic && lic.activation_usage >= lic.activation_limit && message.includes('activation limit')) {
return { state: 'limit-reached', used: lic.activation_usage, limit: lic.activation_limit };
}
return { state: 'refused', reason: message }; // expired, disabled, unknown key
}
return { state: 'unavailable', retryAfter: r.retryAfter }; // 429 or 5xx
}
Example output:
fingerprint length: 64
1: { state: 'activated' }
2: { state: 'activated' } same seat: true
limit: { state: 'limit-reached', used: 3, limit: 3 }
expired: { state: 'refused', reason: 'This license key has expired.' }
unknown: { state: 'refused', reason: 'license_key not found.' }
429: { state: 'unavailable', retryAfter: 60 }
offline: { state: 'unavailable' }
Line 2 is the same computer activating twice. The stub, like the API, returned the same seat because the fingerprint matched.
When every seat is taken
The 400 body carries the license with activation_usage and activation_limit, so the window can say “This key is active on 3 of 3 computers”. Then offer a button that opens the customer’s device page, where they enter their key, see each computer and remove one, with no account:
import { shell } from 'electron';
export const openDevicePage = () => shell.openExternal('https://clavem.io/licenses/manage');
Pass shell.openExternal a fixed URL like this one. Electron’s security guidance is not to hand it content you did not write. Do not add a retry button to the limit message, since no retry can succeed until a seat is free.
Deactivate
/** Frees this computer's seat. Resolves to false when the server could not be reached. */
export async function deactivate(base) {
const saved = await load();
if (!saved) return true;
const r = await post(base, 'deactivate', { license_key: saved.key, instance_id: saved.instanceId });
const freed = r !== null && (r.status === 200 || r.status === 404); // 404: the seat was already gone
if (freed) await clear();
return freed;
}
Offline, it returned false and the saved license stayed, which is what you want: keep the ids, tell the customer the seat is still taken, and mention that they can remove this computer from the device page on any device. Offer the button as Move this license, not as part of sign-out and never in a before-quit handler.
What changes with Electron
- A rename loses the saved license, not the seat.
userDatafollows the app name, so the encrypted file is not found after a rename. With the fingerprint, the next activation gets the same seat back. - Reinstalling the app keeps
userDataon most platforms, so the saved license usually survives it. A fresh operating-system install does not, and the fingerprint then changes with it. - Windows MachineGuid and cloned machines. The README says the value is generated at installation, so a machine cloned from one image can share it. Clones then share one seat. Reset it when you build images, or accept the sharing.
- Portable and AppImage builds run from wherever the file is, and the id comes from the OS, not the path, so moving the file does not move the seat.
- Dev machines count.
electron .on your own laptop activates too. Use a license with a higher limit for testing.
Doing this with Clavem
The device limit comes from the product, three by default, and PATCH /v1/admin/licenses/:id can change it for one license. Activation moves a license from inactive to active, and the last deactivation moves it back. The fields and errors are in the API reference.
Questions
What does node-machine-id read on each operating system?
Its documentation says it reads the MachineGuid registry value on Windows, the IOPlatformUUID on macOS and the dbus machine-id file on Linux. By default it returns a SHA-256 hash, and you can ask for the original value.
What happens if I rename my Electron app?
The userData folder follows the app name, so the saved license is not found after the rename. The customer has to enter the key again, and activating with the same fingerprint returns the same seat, so no extra seat is used.
Should I deactivate when the app quits?
No. Quitting does not move a license to another computer. Deactivate only when the customer asks, for example with a Move this license button.