Clavem

License activation and deactivation in a Python app

Call /v1/licenses/activate once per computer with the key, platform.node() and a salted hash of the operating system's machine id, and store the instance id. Do not use uuid.getnode for the fingerprint, because Python can return a random number there.

Activation ties a license key to one computer and returns an instance.id. Validation then sends it at each launch. Python has no portable call for a machine id, so this page is mostly about getting a stable one without a dependency. The post, storage.save, storage.load and storage.clear helpers are those on the validation page.

Reading a machine id

The API accepts an optional fingerprint of up to 200 characters. With one, activating again from the same computer returns the same seat and updates its name. The obvious Python call is the wrong one. uuid.getnode() returns a MAC address, and the Python documentation says that when every attempt to find one fails it chooses a random 48-bit number. A fingerprint that changes between runs uses a seat each time.

Read the operating system’s id instead, then hash it with a constant that belongs to your app:

import hashlib
import re
import subprocess
import sys
from pathlib import Path

APP_SALT = "com.example.inkwell"  # a constant of your own


def machine_id() -> str | None:
    try:
        if sys.platform == "darwin":
            out = subprocess.run(["/usr/sbin/ioreg", "-rd1", "-c", "IOPlatformExpertDevice"],
                                 capture_output=True, text=True, timeout=5).stdout
            match = re.search(r'"IOPlatformUUID" = "([^"]+)"', out)
            return match.group(1) if match else None
        if sys.platform == "win32":
            import winreg
            with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\Microsoft\Cryptography", 0,
                                winreg.KEY_READ | winreg.KEY_WOW64_64KEY) as key:
                return winreg.QueryValueEx(key, "MachineGuid")[0]
        for path in ("/etc/machine-id", "/var/lib/dbus/machine-id"):
            text = Path(path).read_text().strip()
            if text:
                return text
    except (OSError, subprocess.SubprocessError, ImportError):
        pass
    return None


def fingerprint() -> str | None:
    raw = machine_id()
    return hashlib.sha256(f"{APP_SALT}:{raw}".encode()).hexdigest() if raw else None

The macOS branch ran and returned 64 hex characters. They read the same values the node-machine-id package documents. The KEY_WOW64_64KEY flag makes a 32-bit Python read the 64-bit registry view, where MachineGuid lives.

Activate

import platform


def activate(key: str, *, base: str = BASE) -> dict:
    """{'state': 'activated' | 'limit-reached' | 'refused' | 'unavailable', ...}"""
    body = {"license_key": key, "instance_name": platform.node() or "Computer"}
    if fp := fingerprint():
        body["fingerprint"] = fp
    reply = post("activate", body, base=base)
    if reply is None:
        return {"state": "unavailable"}
    message = reply.body.get("error") or "Activation failed."
    instance = reply.body.get("instance") or {}
    if reply.status == 200 and instance.get("id") and reply.body.get("token"):
        storage.save({"key": key, "instance_id": instance["id"], "token": reply.body["token"]})
        return {"state": "activated"}
    if reply.status in (400, 404):
        lic = reply.body.get("license_key") or {}
        used, limit = lic.get("activation_usage"), lic.get("activation_limit")
        if isinstance(used, int) and isinstance(limit, int) and used >= limit and "activation limit" in message:
            return {"state": "limit-reached", "used": used, "limit": limit}
        return {"state": "refused", "reason": message}   # expired, disabled, unknown key
    return {"state": "unavailable", "retry_after": reply.retry_after}  # 429 or 5xx

Run against a local stub that returns the documented responses, with no live activation:

fingerprint length: 64
uuid.getnode() twice: True multicast bit set: False
1: {'state': 'activated'}
2: {'state': 'activated'} same seat: True
TEST-LIMIT: {'state': 'limit-reached', 'used': 3, 'limit': 3}
TEST-EXPIRED: {'state': 'refused', 'reason': 'This license key has expired.'}
NOPE: {'state': 'refused', 'reason': 'license_key not found.'}
TEST-429: {'state': 'unavailable', 'retry_after': 60.0}
offline: {'state': 'unavailable'}

On this Mac uuid.getnode() found a real address and returned the same value twice, so the failure is not visible here. It appears on machines and containers with no hardware address, which is why you should not rely on it. Line 2 is the same computer activating twice, which returned the same seat.

When every seat is taken

The 400 reply carries the license with activation_usage and activation_limit, so a command-line tool can print “3 of 3 computers are in use”. Point the customer to the device page at /licenses/manage. They enter their key, see each computer and remove one, with no account. Exit with a clear message. A retry cannot succeed until a seat is free.

Deactivate

def deactivate(*, base: str = BASE) -> bool:
    """Frees this computer's seat. False means the server could not be reached: the seat stays taken."""
    saved = storage.load()
    if not saved:
        return True
    reply = post("deactivate", {"license_key": saved["key"], "instance_id": saved["instance_id"]}, base=base)
    freed = reply is not None and reply.status in (200, 404)  # 404: the seat was already gone
    if freed:
        storage.clear()
    return freed

Offline, it returned False and the saved license stayed. Keep the ids, say that the seat is still taken, and mention that the customer can remove this computer from the device page. Wire it to a command such as inkwell license deactivate, not to atexit. Exiting is not moving.

What differs in Python deployments

  • Virtual environments and containers. The id comes from the OS, not from the environment. Two virtualenvs on one computer share a seat. Two containers built from an image that contains /etc/machine-id also share it.
  • CI. Each fresh runner has its own id and activates a new seat. Activate once, run, and call deactivate in a finally block. The seat is not freed if the runner is killed.
  • Scripts and notebooks. If your product is a library used in scripts, pass the key through an environment variable and skip the keyring.
  • Frozen apps. ioreg and the registry work the same in a PyInstaller build. Run the build once to confirm that no console window flashes on Windows when the subprocess starts.

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. See the API reference for the fields and errors.

Questions

Can I use uuid.getnode as a device fingerprint in Python?

No. It returns the MAC address of a network interface, which can change with the adapter in use, and when Python cannot find one it returns a random 48-bit number. That would give a different value on each run.

What identifier should a Python app send as the fingerprint?

The operating system's own machine id, hashed with a string specific to your app. That is the hardware UUID on macOS, MachineGuid on Windows and the machine-id file on Linux. Send the hash, never the raw value.

What if there is no machine id to read?

Activate without a fingerprint. It still works, but reinstalling takes a second seat until the customer removes the first one on the device page. A random id stored in the keyring is a weaker substitute that survives upgrades but not a wiped profile.

Sources

  1. Python docs, uuid.getnode (checked November 2026)