Activation is one POST that ties a key to one machine and returns an instance.id. Validation sends that id on every run. This page covers what is specific to Rust tools: the machine id crate, the limit error, and a Drop guard for CI jobs and short-lived CLI runs. It assumes the Client and its post helper from the validation page.
A fingerprint from machine-uid
The API takes an optional fingerprint, up to 200 characters. With one, activating again from the same machine returns the same seat and updates its name. Without one, every fresh install takes another seat. The machine-uid crate reads the id the operating system already keeps. Its README says the Linux machine id should be treated as confidential, so hash it with a string that only your program uses:
use sha2::{Digest, Sha256};
pub fn fingerprint(salt: &str) -> Option<String> {
let id = machine_uid::get().ok()?; // IOPlatformUUID, MachineGuid or the machine-id file
let digest = Sha256::digest(format!("{salt}:{id}").as_bytes());
Some(digest.iter().map(|b| format!("{b:02x}")).collect())
}
pub fn device_name() -> String {
hostname::get().map(|h| h.to_string_lossy().into_owned()).unwrap_or_else(|_| "Computer".into())
}
The result is 64 hex characters. When machine_uid::get fails, send no fingerprint. Activation still works, and the cost is one extra seat per reinstall.
Activate
#[derive(Debug)]
pub enum Activation {
Activated { instance_id: String, token: String },
LimitReached { used: u64, limit: u64 },
Refused(String), // expired, disabled, unknown key, bad request
NoAnswer { retry_after: Option<std::time::Duration> },
}
impl Client {
pub fn activate(&self, key: &str) -> Activation {
let mut body = json!({ "license_key": key, "instance_name": device_name() });
if let Some(fp) = fingerprint("com.example.inkwell") { body["fingerprint"] = json!(fp); }
let Ok(r) = self.post("activate", body) else { return Activation::NoAnswer { retry_after: None } };
let message = r.body["error"].as_str().unwrap_or("Activation failed.").to_string();
match r.status {
200 => match (r.body["instance"]["id"].as_str(), r.body["token"].as_str()) {
(Some(id), Some(token)) => Activation::Activated { instance_id: id.into(), token: token.into() },
_ => Activation::NoAnswer { retry_after: None },
},
400 | 404 => {
let lic = &r.body["license_key"];
match (lic["activation_usage"].as_u64(), lic["activation_limit"].as_u64()) {
(Some(used), Some(limit)) if used >= limit && message.contains("activation limit")
=> Activation::LimitReached { used, limit },
_ => Activation::Refused(message),
}
}
_ => Activation::NoAnswer { retry_after: r.retry_after },
}
}
}
Save the instance id and token as soon as you get them. Against a local stub that returns the documented responses, with no live activation, the enum gave:
fingerprint length: Some(64)
activated twice, same seat: true
limit: LimitReached { used: 3, limit: 3 }
expired: Refused("This license key has expired.")
unknown: Refused("license_key not found.")
429: NoAnswer { retry_after: Some(60s) }
When every seat is taken
The 400 body carries the license, with activation_usage and activation_limit, so the CLI can print “3 of 3 devices are in use” and point to the customer’s device page at /licenses/manage. There they enter their key, see each device and remove one, with no account and no mail to you. Exit with a clear non-zero status and do not retry: no retry can succeed until a seat is free.
Deactivate, and a Drop guard for short runs
impl Client {
/// True when the seat is free: the server said so, or said it was already gone (404).
pub fn deactivate(&self, key: &str, instance_id: &str) -> bool {
match self.post("deactivate", json!({ "license_key": key, "instance_id": instance_id })) {
Ok(r) => r.status == 200 || r.status == 404,
Err(_) => false,
}
}
}
/// For CI jobs and one-shot runs on throwaway machines: frees the seat when the value goes out of scope.
pub struct Seat<'a> { client: &'a Client, key: String, instance_id: String }
impl Drop for Seat<'_> {
fn drop(&mut self) {
let _ = self.client.deactivate(&self.key, &self.instance_id);
}
}
Without the guard, an ephemeral CI runner activates with a new fingerprint on every job and fills the limit within a few runs. With it, the seat is freed when the job’s main returns. Drop does not run after std::process::exit, after a panic with panic = "abort", or when the runner is killed, so treat it as best effort. A 404 on deactivate means the seat was already gone, which the code counts as success. When deactivate cannot reach the server it returns false: keep the saved instance id and tell the user the seat is still taken.
What differs by platform
- Linux servers and containers. A
machine-idfile copied into an image or a cloned VM gives every copy the same fingerprint, so they share one seat. If that is not what you want, reset the file when you build images. If seats per container are the intent, derive the fingerprint from something per-instance instead. - Windows.
MachineGuidnormally survives reinstalling your application, and changes when Windows is reinstalled. - macOS. The hardware UUID is stable across macOS reinstalls.
- No fingerprint at all. Reinstalls take a new seat each time, until the customer removes the old ones.
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. The activation and deactivation fields and errors are in the API reference. Activation moves a license from inactive to active, and the last deactivation moves it back. For the check that runs after activation, see license key validation in Rust.
Questions
How do I get a machine id in Rust?
The machine-uid crate returns the operating system's own id without root. That is the hardware UUID on macOS, MachineGuid on Windows and the machine-id file on Linux. Hash it with a salt before you send it, because it should not leave the machine.
Do containers and cloned servers share a machine id?
They can. A machine-id file baked into a container or a cloned VM image is copied with it, so every copy reports one id and counts as one device. Reset it when you build images, or do not send a fingerprint there.
Does Drop always free the seat?
No. Drop runs on a normal return and on unwinding, but not after std::process::exit, a panic with abort, or a killed process. Treat it as best effort and let customers remove devices on the device page.