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-idalso share it. - CI. Each fresh runner has its own id and activates a new seat. Activate once, run, and call
deactivatein afinallyblock. 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.
ioregand 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.