Activation ties a license key to one Mac and returns an instance.id. Validation then sends that id on every launch. This page covers the part that is specific to macOS: the identifier, the limit error, and what happens when a customer changes Mac.
A stable device identifier
The API takes an optional fingerprint, up to 200 characters. With one, activating twice from the same Mac returns the first seat. Without one, every reinstall uses another seat until the customer removes the old one. On a Mac the stable value is IOPlatformUUID. Hash it with a string that only your app uses, so the value cannot be matched to anything outside it:
import CryptoKit
import Foundation
import IOKit
enum Device {
static func fingerprint(salt: String = "com.example.inkwell") -> String? {
let entry = IOServiceGetMatchingService(kIOMainPortDefault, IOServiceMatching("IOPlatformExpertDevice"))
guard entry != IO_OBJECT_NULL else { return nil }
defer { IOObjectRelease(entry) }
guard let uuid = IORegistryEntryCreateCFProperty(entry, "IOPlatformUUID" as CFString, kCFAllocatorDefault, 0)?
.takeRetainedValue() as? String else { return nil }
return SHA256.hash(data: Data((salt + ":" + uuid).utf8)).map { String(format: "%02x", $0) }.joined()
}
/// What the customer sees on the device page.
static var name: String { Host.current().localizedName ?? "Mac" }
}
kIOMainPortDefault needs macOS 12 or later. The result is 64 hex characters. If the lookup fails, send no fingerprint: activation still works.
Activate
The reply is either a seat or one of four refusals. An enum keeps the screens honest:
enum ActivationResult {
case activated(instanceID: String, token: String)
case limitReached(used: Int, limit: Int)
case refused(String) // expired, disabled, unknown key, bad request
case noAnswer(retryAfter: TimeInterval?) // offline, 429 or 5xx
}
extension LicenseClient {
func activate(key: String) async -> ActivationResult {
var body = ["license_key": key, "instance_name": Device.name]
if let fp = Device.fingerprint() { body["fingerprint"] = fp }
guard let r = await post("activate", body) else { return .noAnswer(retryAfter: nil) }
switch r.status {
case 200:
guard let instance = r.json["instance"] as? [String: Any], let id = instance["id"] as? String,
let token = r.json["token"] as? String else { return .noAnswer(retryAfter: nil) }
return .activated(instanceID: id, token: token)
case 400, 404:
let message = r.json["error"] as? String ?? "Activation failed."
if let lic = r.json["license_key"] as? [String: Any],
let used = lic["activation_usage"] as? Int, let limit = lic["activation_limit"] as? Int,
message.contains("activation limit") { return .limitReached(used: used, limit: limit) }
return .refused(message)
default:
return .noAnswer(retryAfter: r.retryAfter)
}
}
}
post(_:_:) is the helper from the validation page. Store the instance id and token in the Keychain as soon as you get them. Run against a local stub that returns the documented responses (never against live activation), the enum gave:
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(retryAfter: Optional(60.0))
When every seat is taken
The 400 body for the limit carries the license with activation_usage and activation_limit, so you can say “3 of 3 Macs are in use” instead of showing a raw error. Then send the customer to the device page at /licenses/manage: they enter their key, see which Macs hold a seat, and remove one with no account and no email from you. Do not offer a retry button. Retrying cannot succeed until a seat is free.
Deactivate
extension LicenseClient {
/// Frees this Mac's seat. False means the server could not be reached.
func deactivate(key: String, instanceID: String) async -> Bool {
guard let r = await post("deactivate", ["license_key": key, "instance_id": instanceID]) else { return false }
return r.status == 200 || r.status == 404 // 404: the seat was already gone
}
}
Clear the Keychain items only when this returns true. If it returns false, keep them, tell the customer the seat is still taken, and mention the device page. The customer can also remove that Mac later from the device page on any computer. A removed instance id is gone for good, and a second deactivate answers 404, which the code above treats as success.
What changes on a Mac
- No uninstall hook. Dragging the app to the Trash runs none of your code, so the seat stays taken. Put Deactivate this Mac in the license window or the app menu, and say on your download page that it exists.
- A new Mac, same Keychain. Apple documents that
kSecAttrAccessibleAfterFirstUnlockitems migrate to a new device with encrypted backups. Store the instance id and token withkSecAttrAccessibleAfterFirstUnlockThisDeviceOnlyinstead, and keep only the key in the migratable class. The new Mac then has a key and no instance id, which is the signal to activate. - Check
fp. The token carries the fingerprint asfp. If it differs fromDevice.fingerprint(), the stored token came from another machine. - Virtual machines. A macOS VM reports whatever hardware UUID its hypervisor gives it. A cloned VM image can report the same one as its source, so two clones count as one device. Test in the VM setup your customers use.
- Logic board replacement. The hardware UUID can change with a repair. The customer then needs a new seat, and removes the old one on the device page.
Doing this with Clavem
The device limit comes from the product, three by default, and you can change it for one license with PATCH /v1/admin/licenses/:id. The activation, deactivation and error fields are in the API reference. Customers see their devices on the device page without an account. For the launch-time check after activation, see license key validation in Swift.
Questions
What identifier should a Mac app send as the fingerprint?
Hash the IOPlatformUUID, the hardware UUID that IOKit reports, together with a string specific to your app. Send the hash, never the raw UUID. The API accepts up to 200 characters.
Can an app free its seat when it is dragged to the Trash?
No. Moving an app to the Trash runs none of your code. Offer a Deactivate this Mac button in the license window, and point customers to the device page where they can remove a Mac themselves.
What happens if a customer reinstalls macOS on the same Mac?
The hardware UUID stays the same, so activating again with the same fingerprint returns the existing seat, with its name updated, instead of using a second one.