Activation ties a license key to one computer and returns an instance.id. Validation then sends it on each launch. This page covers the Java specifics: where a machine id comes from in a language that has none, and how to read the reply without surprises. The Java code in this guide was not compiled or run, because the JDK available for testing was Java 8 and the code needs Java 17. It reuses the LicenseClient fields and the Jackson mapper from the validation page.
A fingerprint
The API accepts an optional fingerprint, up to 200 characters. With one, activating again from the same computer returns the same seat and updates its name. Without one, each reinstall takes another seat. OSHI reads the hardware UUID on Windows, macOS and Linux with no native setup. Hash it with a constant that belongs to your app, so the value you send cannot be matched to anything outside it:
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Optional;
import oshi.SystemInfo;
public final class Device {
private static final String SALT = "com.example.inkwell"; // a constant of your own
public static Optional<String> fingerprint() {
return machineId().map(id -> {
try {
byte[] digest = MessageDigest.getInstance("SHA-256").digest((SALT + ":" + id).getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(digest);
} catch (java.security.NoSuchAlgorithmException e) {
throw new IllegalStateException(e); // every JRE has SHA-256
}
});
}
private static Optional<String> machineId() {
try {
String uuid = new SystemInfo().getHardware().getComputerSystem().getHardwareUUID();
if (uuid != null && !uuid.isBlank() && !uuid.equalsIgnoreCase("unknown")) return Optional.of(uuid);
} catch (RuntimeException | LinkageError e) {
// OSHI could not read it: fall through
}
try {
for (String file : new String[] {"/etc/machine-id", "/var/lib/dbus/machine-id"}) {
Path path = Path.of(file);
if (Files.isReadable(path)) {
String id = Files.readString(path).trim();
if (!id.isEmpty()) return Optional.of(id);
}
}
} catch (java.io.IOException e) {
// no machine-id file
}
return Optional.empty();
}
/** What the customer sees on the device page. Avoids InetAddress.getLocalHost(), which can block on DNS. */
public static String name() {
String name = System.getenv("COMPUTERNAME"); // Windows
if (name == null) name = System.getenv("HOSTNAME"); // many Linux shells
return name != null && !name.isBlank() ? name : "Computer";
}
}
The result is 64 hex characters. If both sources fail, send no fingerprint. Activation still works, and the cost is one extra seat per reinstall. OSHI can return unknown for the UUID on some virtual machines, which is why the code filters it, since every such machine would then share one fingerprint.
Activate
Jackson’s tree model handles the null that an unlimited license sends for activation_limit, because isInt() is false for a JSON null:
public enum ActivationKind { ACTIVATED, LIMIT_REACHED, REFUSED, UNAVAILABLE }
public record Activation(ActivationKind kind, String instanceId, String token, String reason, int used, int limit) {}
public Activation activate(String key) {
Map<String, String> body = new HashMap<>();
body.put("license_key", key);
body.put("instance_name", Device.name());
Device.fingerprint().ifPresent(fp -> body.put("fingerprint", fp));
try {
HttpRequest request = HttpRequest.newBuilder(base.resolve("/v1/licenses/activate"))
.timeout(Duration.ofSeconds(8))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json.writeValueAsString(body)))
.build();
HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
JsonNode reply = parse(response.body());
String message = reply.path("error").textValue();
switch (response.statusCode()) {
case 200:
if (reply.path("instance").path("id").isTextual() && reply.path("token").isTextual())
return new Activation(ActivationKind.ACTIVATED, reply.path("instance").path("id").asText(),
reply.path("token").asText(), null, 0, 0);
return new Activation(ActivationKind.UNAVAILABLE, null, null, null, 0, 0);
case 400:
case 404:
JsonNode lic = reply.path("license_key");
if (lic.path("activation_usage").isInt() && lic.path("activation_limit").isInt()
&& lic.path("activation_usage").asInt() >= lic.path("activation_limit").asInt()
&& message != null && message.contains("activation limit"))
return new Activation(ActivationKind.LIMIT_REACHED, null, null, message,
lic.path("activation_usage").asInt(), lic.path("activation_limit").asInt());
return new Activation(ActivationKind.REFUSED, null, null, message, 0, 0); // expired, disabled, unknown key
default:
return new Activation(ActivationKind.UNAVAILABLE, null, null, null, 0, 0); // 429 or 5xx
}
} catch (IOException e) {
return new Activation(ActivationKind.UNAVAILABLE, null, null, null, 0, 0); // offline or timeout
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return new Activation(ActivationKind.UNAVAILABLE, null, null, null, 0, 0);
}
}
On ACTIVATED, save the key, the instance id and the token in the keyring entry from the validation page. Run activate on a worker thread: it blocks.
When every seat is taken
The 400 body carries the license with activation_usage and activation_limit. Say “This key is active on 3 of 3 computers” and offer a button that opens the device page. The customer enters their key, sees each computer and removes one, with no account:
java.awt.Desktop.getDesktop().browse(java.net.URI.create("https://clavem.io/licenses/manage"));
Check Desktop.isDesktopSupported() first, since headless environments do not support it. Do not offer a retry: it cannot succeed until a seat is free.
Deactivate
/** True when the seat is free: the server said so, or said it was already gone (404). */
public boolean deactivate(String key, String instanceId) {
try {
HttpRequest request = HttpRequest.newBuilder(base.resolve("/v1/licenses/deactivate"))
.timeout(Duration.ofSeconds(8))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json.writeValueAsString(Map.of("license_key", key, "instance_id", instanceId))))
.build();
int status = http.send(request, HttpResponse.BodyHandlers.discarding()).statusCode();
return status == 200 || status == 404;
} catch (IOException e) {
return false;
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return false;
}
}
On true, delete the saved license. On false, keep the ids, say that the seat is still taken, and mention the device page. Wire it to a menu item named Move this license, not to a shutdown hook. Quitting is not moving.
What differs on the JVM
- Docker and CI. A container usually has no machine-id file and OSHI may return nothing useful, so you activate without a fingerprint and each container run could take a seat. Activate once, run, and deactivate in a
finallyblock. - Cloned images. A hardware UUID or machine-id copied with a VM image gives every clone one fingerprint, so clones share a seat.
- jpackage and GraalVM. OSHI uses reflection and JNA. Test the packaged app, not just the IDE run.
- Android.
ANDROID_IDis the usual identifier there, and OSHI does not apply.
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
How do I get a machine id in Java?
The JDK has no API for it. The OSHI library returns the hardware UUID through SystemInfo, and on Linux you can read the machine-id file directly. Hash the result with a salt that belongs to your app before you send it.
Why avoid InetAddress.getLocalHost for the device name?
It resolves the host name through DNS, and on a machine with a broken resolver it can wait a long time. Read the COMPUTERNAME or HOSTNAME environment variable, or ask OSHI, and treat the name as a label only.
What happens when a Java app is reinstalled?
The hardware UUID is the same, so activating again with the same fingerprint returns the existing seat and updates its name. Without a fingerprint, each reinstall would take another seat.