Clavem

License activation and deactivation in a Go app

Call /v1/licenses/activate once per computer with the key, the hostname and machineid.ProtectedID as the fingerprint, then save the instance id. The reply decodes into a struct, and a null activation_limit for an unlimited license becomes a nil pointer.

Activation ties a license key to one computer and returns an instance.id. Validation then sends it on each run. This page covers the Go specifics: a library that returns a hashed machine id, reply decoding with typed structs, and the container cases that break fingerprints. It reuses Client.post and the keyring helpers 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. The machineid package reads the operating system’s id, and its README names the sources: IOPlatformUUID on macOS, MachineGuid on Windows, and the D-Bus machine-id file on Linux. ProtectedID does the salting for you. Its README describes it as an HMAC-SHA256 of the app id, keyed by the machine id:

import "github.com/denisbrodbeck/machineid"

// Fingerprint returns "" when the system has no readable machine id.
func Fingerprint() string {
	id, err := machineid.ProtectedID("com.example.inkwell")
	if err != nil {
		return ""
	}
	return id
}

The result is 64 hex characters. Use a constant app id and never change it, since a new app id means a new fingerprint for every customer. If the call fails, send no fingerprint. Activation still works, at the cost of a seat per reinstall.

Activate

Decode into a struct and the awkward cases disappear. activation_limit is null for an unlimited license, so it is a *int:

type ActivationKind int

const (
	Activated ActivationKind = iota
	LimitReached
	Refused     // expired, disabled, unknown key, bad request
	Unavailable // offline, 429 or 5xx
)

type Activation struct {
	Kind       ActivationKind
	InstanceID string
	Token      string
	Reason     string
	Used, Limit int
	RetryAfter time.Duration
}

func (c *Client) Activate(ctx context.Context, key string) Activation {
	name, _ := os.Hostname()
	body := map[string]string{"license_key": key, "instance_name": name}
	if fp := Fingerprint(); fp != "" {
		body["fingerprint"] = fp
	}
	status, raw, retry, err := c.post(ctx, "activate", body)
	if err != nil {
		return Activation{Kind: Unavailable}
	}
	var r struct {
		Error    string `json:"error"`
		Token    string `json:"token"`
		Instance *struct {
			ID string `json:"id"`
		} `json:"instance"`
		License *struct {
			Usage *int `json:"activation_usage"`
			Limit *int `json:"activation_limit"` // null when unlimited
		} `json:"license_key"`
	}
	_ = json.Unmarshal(raw, &r)

	switch status {
	case http.StatusOK:
		if r.Instance == nil || r.Token == "" {
			return Activation{Kind: Unavailable}
		}
		return Activation{Kind: Activated, InstanceID: r.Instance.ID, Token: r.Token}
	case http.StatusBadRequest, http.StatusNotFound:
		if l := r.License; l != nil && l.Usage != nil && l.Limit != nil && *l.Usage >= *l.Limit &&
			strings.Contains(r.Error, "activation limit") {
			return Activation{Kind: LimitReached, Reason: r.Error, Used: *l.Usage, Limit: *l.Limit}
		}
		return Activation{Kind: Refused, Reason: r.Error}
	}
	return Activation{Kind: Unavailable, RetryAfter: retry}
}

On Activated, call Save(Saved{Key: key, InstanceID: ..., Token: ...}). A pointer for each nullable number is the Go answer to “the API sends null here”.

When every seat is taken

The 400 body carries the license with activation_usage and activation_limit. Print “This key is active on 3 of 3 computers” and the address of the device page, https://clavem.io/licenses/manage. The customer enters their key there, sees each computer and removes one, with no account. Exit with a non-zero status and do not retry. No retry can succeed until a seat is free.

Deactivate

// Deactivate frees this computer's seat. It returns false when the server could not be reached.
func (c *Client) Deactivate(ctx context.Context, key, instanceID string) bool {
	status, _, _, err := c.post(ctx, "deactivate", map[string]string{"license_key": key, "instance_id": instanceID})
	return err == nil && (status == http.StatusOK || status == http.StatusNotFound) // 404: the seat was already gone
}

On true, call Clear(). On false, keep the saved ids, say that the seat is still taken, and mention the device page. Offer it as a license deactivate subcommand, not as a deferred call at exit.

What differs in Go programs

  • Containers have no machine id. Many images lack the D-Bus machine-id file, so ProtectedID returns an error and the program activates without a fingerprint. Two containers then take two seats, which may be what you want for per-instance licensing.
  • Hostnames in containers are random. Use a --name flag or an environment variable for instance_name.
  • Cross-compiled binaries ask the target. The id is read at run time on the customer’s machine, not at build time, so one build serves every customer.
  • CI runners. Each fresh runner is a new machine and activates a new seat. Activate once, run, and defer the deactivate in main. A killed runner never frees its seat.
  • go test on a laptop reads your own machine id. Inject the fingerprint function in tests so they do not depend on it.

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. Activation moves a license from inactive to active, and the last deactivation moves it back. See the API reference for the fields and errors.

Questions

How do I get a machine id in Go?

The denisbrodbeck/machineid package reads the operating system's own id without admin rights. ProtectedID takes your app name and returns an HMAC-SHA256 of it keyed by the machine id, so the raw id never leaves the machine.

Why is there no machine id inside my Docker container?

The package's README says Linux uses the D-Bus machine-id file, which many container images do not have. Without it ProtectedID returns an error. Activate without a fingerprint, or pass a stable id of your own.

What does os.Hostname return in a container?

Usually the container id, which changes on every run. Use it only as a label, and let users override it with a flag or an environment variable so the device page shows something recognizable.

Sources

  1. denisbrodbeck/machineid README (checked November 2026)