Activation ties a license key to one computer and returns an instance.id. Validation sends it at each launch. Qt makes the hard part of activation short, because QSysInfo already knows the machine id. This page covers the fingerprint, the activation reply, and the cases where Qt’s machine id needs a second look. None of the Qt code here was compiled or run: no Qt installation was available.
The fingerprint
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. Qt provides the machine id as a QByteArray. Hash it with a constant that belongs to your app, so the value you send cannot be matched to anything outside it:
#include <QCryptographicHash>
#include <QSysInfo>
QString fingerprint() {
const QByteArray id = QSysInfo::machineUniqueId();
if (id.isEmpty()) return {}; // no id on this system: activate without one
const QByteArray salted = QByteArrayLiteral("com.example.inkwell:") + id;
return QString::fromLatin1(QCryptographicHash::hash(salted, QCryptographicHash::Sha256).toHex());
}
QString deviceName() { return QSysInfo::machineHostName(); } // what the customer sees on the device page
Qt’s documentation is direct about the limits. The function returns an empty byte array when no unique id can be determined. On some systems the value persists across reboots and on others it does not, and applications should not depend on that without checking the operating system. On Linux the id is usually permanent and matches the D-Bus machine id, with exceptions for nodes without their own storage. Test on each platform you ship, and reboot. The fingerprint is 64 hex characters.
Activate
Activation needs the same asynchronous POST as validation. Pull it into a helper that both calls can share:
using JsonCallback = std::function<void(int status, const QJsonObject& json, std::optional<int> retryAfter)>;
void LicenseClient::postJson(const QString& action, const QJsonObject& body, JsonCallback done) {
QNetworkRequest request(m_base.resolved(QUrl("/v1/licenses/" + action)));
request.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");
request.setTransferTimeout(std::chrono::seconds(8));
QNetworkReply* reply = m_nam.post(request, QJsonDocument(body).toJson(QJsonDocument::Compact));
connect(reply, &QNetworkReply::finished, this, [reply, done = std::move(done)] {
reply->deleteLater();
bool ok = false;
const int wait = reply->rawHeader("Retry-After").toInt(&ok);
done(reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt(), // 0: no HTTP answer
QJsonDocument::fromJson(reply->readAll()).object(), ok ? std::optional<int>(wait) : std::nullopt);
});
}
struct Activation {
enum class Kind { Activated, LimitReached, Refused, Unavailable } kind;
QString instanceId, token, reason;
int used = 0, limit = 0;
};
void LicenseClient::activate(const QString& key) {
QJsonObject body{{"license_key", key}, {"instance_name", deviceName()}};
if (const QString fp = fingerprint(); !fp.isEmpty()) body["fingerprint"] = fp;
postJson("activate", body, [this](int status, const QJsonObject& json, std::optional<int>) {
const QString message = json["error"].toString();
if (status == 200 && json["instance"].isObject() && json["token"].isString())
return emit activated({Activation::Kind::Activated, json["instance"]["id"].toString(), json["token"].toString(), {}});
if (status == 400 || status == 404) {
const QJsonObject lic = json["license_key"].toObject();
const int used = lic["activation_usage"].toInt(-1), limit = lic["activation_limit"].toInt(-1);
if (used >= 0 && limit >= 0 && used >= limit && message.contains("activation limit"))
return emit activated({Activation::Kind::LimitReached, {}, {}, message, used, limit});
return emit activated({Activation::Kind::Refused, {}, {}, message}); // expired, disabled, unknown key
}
emit activated({Activation::Kind::Unavailable, {}, {}, {}}); // offline, 429 or 5xx
});
}
Qt’s JSON accessors return the default for a null field, so activation_limit: null on an unlimited license reads as -1 and does not throw. The activation limit error is a 400 whose body includes the license with activation_usage and activation_limit. Save the instance id and the token in QtKeychain as soon as you get them.
When every seat is taken
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 every computer and removes one, with no account. A retry cannot succeed until a seat is free, so do not offer one:
#include <QDesktopServices>
QDesktopServices::openUrl(QUrl("https://clavem.io/licenses/manage"));
Deactivate
void LicenseClient::deactivate(const QString& key, const QString& instanceId) {
postJson("deactivate", {{"license_key", key}, {"instance_id", instanceId}},
[this](int status, const QJsonObject&, std::optional<int>) {
emit deactivated(status == 200 || status == 404); // 404: the seat was already gone
});
}
On true, delete the stored license. On false, keep the saved ids and say that the seat is still taken and can be removed from the device page. Connect it to a menu action named Move this license, not to aboutToQuit: quitting is not moving.
What differs in Qt apps
- Empty ids happen. If
machineUniqueId()is empty, send no fingerprint, or use a randomQUuidstored in QtKeychain. The second survives upgrades but not a wiped profile. - Cloned images. A machine id copied with a VM or container image gives every clone the same fingerprint, so clones share one seat.
- Hostnames.
machineHostName()can beAda-s-MacBook-Pro.local. That is fine, sinceinstance_nameis only a label for the customer. - Qt on mobile. If you ship on Android or iOS, check what
machineUniqueId()returns there before relying on it. - Sandboxes. Flatpak and Snap apps may see a different
/etc/machine-idthan the host. Test inside the package you ship.
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 QSysInfo::machineUniqueId be used as a license fingerprint?
Usually, with care. Qt documents that it returns an empty byte array when no id can be found, and that on some systems the value persists across reboots and on others it does not. Test it on every platform you ship, and hash it before you send it.
What should I do when machineUniqueId is empty?
Activate without a fingerprint. Activation still works, but each reinstall then takes another seat until the customer removes the old one. A random id stored in QtKeychain is a weaker substitute that survives upgrades.
How do I let a customer manage their computers?
Open the device page with QDesktopServices::openUrl. They enter their key, see every computer using it and remove one, with no account.