Clavem

Validate a license key in a Wails desktop app

In Wails, make the license check in Go, not in the JavaScript front end. Bind a Check method that posts to /v1/licenses/validate under a context deadline and returns only a state to the webview, and keep the key and token in the operating system's keychain.

Keep the logic in Go

A Wails window is a webview, and anything in its JavaScript can be read with the inspector. The license logic belongs in the Go backend, where the key, the instance id and the token stay. The front end calls a bound method and gets back a short state: licensed, invalid, needs-network or unlicensed.

As of November 2026 the Wails website presents v3.0.0 as the stable release and keeps the v2 documentation at v2.wails.io. The code here is a plain Go package with no Wails imports, so it works in either. Activation is on the activation page and token verification on the offline page; VerifyToken below comes from there.

The client

package license

import (
	"bytes"
	"context"
	"encoding/json"
	"io"
	"net/http"
	"strconv"
	"time"
)

type State string

const (
	Unlicensed   State = "unlicensed"
	Licensed     State = "licensed"
	Invalid      State = "invalid"
	NeedsNetwork State = "needs-network"
)

// Result is all the front end ever sees.
type Result struct {
	State      State  `json:"state"`
	Message    string `json:"message"`     // the server's sentence, for Invalid
	RetryAfter int    `json:"retry_after"` // seconds after a 429 or 503: check again quietly then
}

type Saved struct {
	Key        string `json:"key"`
	InstanceID string `json:"instance_id"`
	Token      string `json:"token"`
}

type Store interface { // the OS keychain in production, memory in tests
	Load() (*Saved, error) // nil, nil when nothing is stored
	Save(Saved) error
	Clear() error
}

type Client struct {
	Base      string // https://clavem.io
	ProductID int64  // from your product page
	PublicKey string // from your product page
	Store     Store
	HTTP      *http.Client // no Timeout: every call sets a deadline through its context
	Now       func() time.Time
}

type reply struct {
	Valid bool   `json:"valid"`
	Error string `json:"error"`
	Token string `json:"token"`
}

// call returns err only for transport failures. A 404, 429 or 503 comes back with err == nil.
func (c *Client) call(ctx context.Context, action string, body map[string]string) (int, reply, time.Duration, error) {
	var r reply
	payload, _ := json.Marshal(body)
	ctx, cancel := context.WithTimeout(ctx, 8*time.Second)
	defer cancel()
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.Base+"/v1/licenses/"+action, bytes.NewReader(payload))
	if err != nil {
		return 0, r, 0, err
	}
	req.Header.Set("Content-Type", "application/json")
	res, err := c.HTTP.Do(req)
	if err != nil {
		return 0, r, 0, err
	}
	defer res.Body.Close()
	_ = json.NewDecoder(io.LimitReader(res.Body, 1<<20)).Decode(&r) // an HTML error page leaves r empty
	seconds, _ := strconv.Atoi(res.Header.Get("Retry-After"))
	return res.StatusCode, r, time.Duration(seconds) * time.Second, nil
}

// Check is the launch-time flow.
func (c *Client) Check(ctx context.Context) Result {
	saved, _ := c.Store.Load()
	if saved == nil {
		return Result{State: Unlicensed}
	}
	status, r, wait, err := c.call(ctx, "validate", map[string]string{"license_key": saved.Key, "instance_id": saved.InstanceID})
	if err == nil {
		switch status {
		case http.StatusOK:
			if r.Token != "" { // keep the new token even when the license is not valid
				saved.Token = r.Token
				_ = c.Store.Save(*saved)
			}
			if r.Valid {
				return Result{State: Licensed}
			}
			return Result{State: Invalid, Message: r.Error}
		case http.StatusNotFound:
			_ = c.Store.Clear() // unknown key, or this device was removed: ask for the key again
			return Result{State: Invalid, Message: r.Error}
		}
	}
	// No network, 400, 429 or 503: trust the stored token while it is fresh.
	out := Result{State: NeedsNetwork, RetryAfter: int(wait.Seconds())}
	if VerifyToken(saved.Token, c.PublicKey).Licensed(c.ProductID, c.Now()) {
		out.State = Licensed
	}
	return out
}

The keychain store and the binding

// keychain.go: go get github.com/zalando/go-keyring
type keychain struct{}

const service, account = "com.example.inkwell", "license"

func (keychain) Load() (*license.Saved, error) {
	raw, err := keyring.Get(service, account)
	if errors.Is(err, keyring.ErrNotFound) {
		return nil, nil
	}
	if err != nil {
		return nil, err
	}
	var s license.Saved
	return &s, json.Unmarshal([]byte(raw), &s)
}
func (keychain) Save(s license.Saved) error {
	b, _ := json.Marshal(s)
	return keyring.Set(service, account, string(b))
}
func (keychain) Clear() error {
	if err := keyring.Delete(service, account); err != nil && !errors.Is(err, keyring.ErrNotFound) {
		return err
	}
	return nil
}

// The struct the front end can call. Only exported methods are bound.
type LicenseService struct{ c *license.Client }

func NewLicenseService() *LicenseService {
	return &LicenseService{c: &license.Client{
		Base: "https://clavem.io", ProductID: 75, PublicKey: "YOUR_PUBLIC_KEY", // from your product page
		Store: keychain{}, HTTP: &http.Client{}, Now: time.Now,
	}}
}

func (s *LicenseService) Check() license.Result { return s.c.Check(context.Background()) }

// Wails v3: Services: []application.Service{application.NewService(svc)} in application.Options.
// Wails v2: Bind: []interface{}{svc} in options.App.

In the webview, await Check() from the generated bindings returns the Result. The binding path depends on your Go module name.

What I ran

I ran the package on the Go Playground, which has no outbound network, against an in-process httptest server that returns the documented response shapes. I did not call Go against the live API, and the Wails binding code was not compiled. The playground fakes time, so the client takes its clock as a field.

Scenario State Notes
Nothing stored unlicensed no request
200, valid: true licensed token replaced
200, valid: false invalid “This license key has expired.”, key kept
404 key or instance invalid keychain cleared
429, fresh token licensed retry_after 60
503, fresh token licensed retry_after 5
503, stale token needs-network retry_after 5
502 with an HTML body licensed body ignored, token used
Connection refused licensed token used

Go and Wails details

  • err == nil on a 429. net/http reports only transport failures as errors, so the status code is part of the result. Test it explicitly, as call does.
  • Deadline, not Client.Timeout. The http.Client timeout includes reading the response body. A client with an 8 second timeout would cut off a large download, so keep one client without a timeout and give each API call a context deadline.
  • Linux without a keyring. go-keyring uses the Secret Service D-Bus interface on Linux, which needs GNOME Keyring or a compatible service. When Load fails with anything other than not found, fall back to a file in os.UserConfigDir().
  • Do not retry in a loop at launch. Return RetryAfter and let the front end call Check again after that many seconds.

Doing this with Clavem

The License API needs no authentication, accepts JSON, and is described field by field in the API reference.

Questions

Can the front end call the License API directly?

Yes, the License API allows cross-origin requests from any origin. But the key and token would then live in JavaScript memory and be visible in developer tools, and the offline check would run in the page. Go keeps them out of it.

Does this work with Wails v2 and v3?

The license package imports nothing from Wails. Only the binding differs: v2 lists the struct in the Bind option, v3 registers it as a service.

Sources

  1. Wails website, v3.0.0 stable release notice (checked November 2026)
  2. Wails v3 documentation, Services (checked November 2026)
  3. Wails v2 documentation, How does it work (checked November 2026)
  4. Go documentation, net/http Client (checked November 2026)
  5. go-keyring README (checked November 2026)