Get started with Go

This guide takes a Go program from nothing to its first activated license, and on to the build you hand to customers: install the SDK, a few lines of code, a test run, the result on the dashboard, errors, and release.

5 min read

What you need

Go 1.23 or later. The SDK uses Go's standard library only, with no other module.
An app on the dashboard. Its Integration › Connect software page has the API address, the App ID, the public key and a Make a test key button. The API address ends in /api, with no /v1: https://<your ClavisAUH site>/api.

1. Install the SDK

Download clavisauh-go-1.0.0.zip from Downloads, check its SHA-256 as that page shows, and unpack it in your project's folder (unzip clavisauh-go-1.0.0.zip, or Expand-Archive clavisauh-go-1.0.0.zip . in PowerShell): it holds one folder, clavisauh-go-1.0.0, with the SDK. A new program first needs its module (go mod init; go mod tidy is not needed); then point it at that folder:

go mod init myapp
go mod edit -require=clavisauh@v0.0.0 -replace=clavisauh=./clavisauh-go-1.0.0

Your go.mod then holds these two lines:

require clavisauh v0.0.0

replace clavisauh => ./clavisauh-go-1.0.0

Then import "clavisauh" in your code. The SDK is not on a module proxy yet; once it is, this guide will show that way too.

2. The minimal code

The blocks below are parts of one file; the whole file, with its imports and helpers, is in step 3.

Create the client once, when your software starts. The API address, App ID and public key are the three values on the Connect software page: the sample reads them from environment variables, your software writes them in its code. The device key lives in a file only the current user can read: sessions and offline tokens are bound to it, while the seat on the license follows the machine's hashed identifiers. DefaultDevice("") describes the machine from hashed identifiers; its argument is the name the dashboard shows, and an empty one uses the host name:

	deviceKey, err := clavisauh.LoadOrCreateDeviceKey(filepath.Join(state, "device.key"))
	if err != nil {
		fail(err)
	}
	client, err := clavisauh.New(clavisauh.Options{
		BaseURL:       os.Getenv("CLAVIS_BASE_URL"),
		AppID:         os.Getenv("CLAVIS_APP_ID"),
		AppPublicKeys: []string{os.Getenv("CLAVIS_APP_KEY")},
		Device:        clavisauh.DefaultDevice(""),
		// The same key every run: sessions and offline tokens stay with this machine.
		DeviceKey:  deviceKey,
		AppVersion: "1.0.0",
	})
	if err != nil {
		fail(err)
	}

Activate the customer's key. Without a network, the offline token saved last time keeps the software running:

	var grant *clavisauh.Grant
	if _, err = client.Init(); err == nil {
		grant, err = client.Activate(os.Getenv("CLAVIS_LICENSE"))
	}
	if err != nil {
		// No answer (network_error, timeout...): a token saved last time keeps the software working.
		var e *clavisauh.Error
		token, _ := os.ReadFile(saved)
		if !errors.As(err, &e) || !e.Retryable() || len(token) == 0 || client.VerifyOffline(string(token)) == nil {
			fail(err)
		}
		fmt.Println("Offline: using the license saved on this machine")
	}

The public key only checks signatures, so embedding it in your software is safe. Never embed any secret key.

3. Run it

On the Connect software page, select Make a test key. A TEST key expires after 24 hours and does not count against your limits.
Save the whole file below as main.go in your project (the starter, with each scenario in a folder of its own, has it as k1_key/main.go and runs go run ./k1_key), set the four settings and run it:

// K1 · License key only: activate on this machine, keep the session alive, work offline for a while.
//
// Run: CLAVIS_BASE_URL=... CLAVIS_APP_ID=... CLAVIS_APP_KEY=... CLAVIS_LICENSE=... go run .
// (saved as main.go in your module; the starter project keeps it in k1_key/ and runs go run ./k1_key)
package main

import (
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"time"

	"clavisauh"
)

func env(name, fallback string) string {
	if v := os.Getenv(name); v != "" {
		return v
	}
	return fallback
}

var (
	lang  = env("CLAVIS_LANG", "en")
	state = env("CLAVIS_STATE_DIR", ".clavis")
	saved = filepath.Join(state, "offline.token")
)

// fail prints the sentence for the user and the code, and stops.
func fail(err error) {
	var e *clavisauh.Error
	if !errors.As(err, &e) {
		e = &clavisauh.Error{Code: "unknown_error", Message: err.Error()}
	}
	fmt.Println(e.UserMessage(lang))
	fmt.Println("FAIL", e.Code)
	os.Exit(1)
}

func main() {
	deviceKey, err := clavisauh.LoadOrCreateDeviceKey(filepath.Join(state, "device.key"))
	if err != nil {
		fail(err)
	}
	client, err := clavisauh.New(clavisauh.Options{
		BaseURL:       os.Getenv("CLAVIS_BASE_URL"),
		AppID:         os.Getenv("CLAVIS_APP_ID"),
		AppPublicKeys: []string{os.Getenv("CLAVIS_APP_KEY")},
		Device:        clavisauh.DefaultDevice(""),
		// The same key every run: sessions and offline tokens stay with this machine.
		DeviceKey:  deviceKey,
		AppVersion: "1.0.0",
	})
	if err != nil {
		fail(err)
	}

	var grant *clavisauh.Grant
	if _, err = client.Init(); err == nil {
		grant, err = client.Activate(os.Getenv("CLAVIS_LICENSE"))
	}
	if err != nil {
		// No answer (network_error, timeout...): a token saved last time keeps the software working.
		var e *clavisauh.Error
		token, _ := os.ReadFile(saved)
		if !errors.As(err, &e) || !e.Retryable() || len(token) == 0 || client.VerifyOffline(string(token)) == nil {
			fail(err)
		}
		fmt.Println("Offline: using the license saved on this machine")
	}

	if grant == nil {
		fmt.Println("OK k1 offline")
		return
	}
	until := "forever"
	if grant.License.ExpiresAt != nil {
		until = grant.License.ExpiresAt.Format(time.RFC3339)
	}
	fmt.Println("License", grant.License.Status, "until", until)
	// Every few minutes while the software runs; sessions end after an hour without one.
	if _, err := client.Heartbeat(); err != nil {
		fail(err)
	}
	if client.OfflineToken != "" {
		if err := os.WriteFile(saved, []byte(client.OfflineToken), 0o600); err != nil {
			fail(err)
		}
	}
	_ = client.Logout()
	fmt.Println("OK k1", grant.License.Status)
}

export CLAVIS_BASE_URL="<API address>"
export CLAVIS_APP_ID="<App ID>"
export CLAVIS_APP_KEY="<public key>"
export CLAVIS_LICENSE="<test key>"
go run .

On Windows, in PowerShell:

$env:CLAVIS_BASE_URL = "<API address>"
$env:CLAVIS_APP_ID = "<App ID>"
$env:CLAVIS_APP_KEY = "<public key>"
$env:CLAVIS_LICENSE = "<test key>"
go run .

The starter project (Download the starter (.zip) on the dashboard's Connect software page, once Go is picked; it is not on the Downloads page) runs this scenario with ./run.sh <key> or .\run.cmd <key>.

It prints License active until <date>, then OK k1 active on the last line. Run it again on the same machine and it still succeeds without using another seat: the server knows the machine by its hashed identifiers (Devices, HWID and transfers). The device key, which signs the requests, stays in the .clavis folder under the folder you run it from (or in CLAVIS_STATE_DIR). A container started afresh for each run looks like a new machine every time, see Questions.

4. See it on the dashboard

Integration › Connect software: step 4 turns to Connected, with go/1.0.0 and the machine's operating system.
Licensing & releases › Licenses: the key goes from Unused to Active.
End users › Devices & sessions: the machine that ran it, and the session it opened.

5. Handle errors

Every refusal returns a *clavisauh.Error, which you get with errors.As. It has three things you need:

e.Code: a code from the error codes table, such as invalid_credentials or device_limit.
e.UserMessage("en"): a sentence for the person using your software, in English or "vi", ready to show.
e.Retryable(): true when no answer arrived (no network, too slow, a busy server); trying again later may work.

When e.Verification is true, the answer did not carry your app's valid signature (code unsigned_response, invalid_response_signature, unknown_key or stale_response). Treat it as no answer at all; usually the API address or the public key in your software is wrong.

While your software runs, send a heartbeat regularly to keep the session, every 5 to 30 minutes or so: a session ends after 60 minutes without one.

	// Every few minutes while the software runs; sessions end after an hour without one.
	if _, err := client.Heartbeat(); err != nil {
		fail(err)
	}

Save the latest offline token, so the software still opens next time without a network:

	if client.OfflineToken != "" {
		if err := os.WriteFile(saved, []byte(client.OfflineToken), 0o600); err != nil {
			fail(err)
		}
	}

Offline tokens come on every plan and last 7 days by default; Premium chooses the length, and Online-Only Mode turns them off. See Offline licenses. To see every call while tracking a problem down, set Debug: clavisauh.DebugStderr in Options: each call and its outcome go to stderr, keys show only their first and last four characters, and passwords never appear.

6. Package and release

Write the API address, App ID and public key in your code or in a config file shipped with the build. Customers' machines need no environment variables.
Put the state folder (device key, offline token) in os.UserConfigDir(), under your software's name. Never in the install folder.
Set AppVersion to the version you release: the server uses it to block builds that are too old and to announce new ones, see Signed releases and updates.
go build gives one executable. It cross-compiles: GOOS=windows GOARCH=amd64 go build makes an .exe on Linux, the way ClavisAUH's CI builds the Go samples it runs on Windows.
Run the build to OK k1 active on a clean machine before you release it.
Before you sell, turn on Publicly released in Integration › App settings. Every TEST key stops working, so a test key that got out cannot be used.

Questions

Does the software need a network every time it opens? Activation and heartbeats do. Without a network, the saved token keeps the software running for 7 days by default, or the length chosen on Premium, checked on the machine without the server.

Can goroutines share one client? Better not: the client is not safe for concurrent use, since each call changes its session state. Keep one client per goroutine, or lock with a sync.Mutex when several places call it.

How do I limit features by license plan? client.Has("feature_name") tells whether the license grants that feature; create features in License plans and entitlements.

What if a customer reinstalls the system or changes machines? After a reinstall on the same machine, the server still recognizes it from its hashed hardware identifiers. A new machine takes a new seat; when none is left the customer gets device_limit, and you Reset devices on the Licenses page. See Devices, HWID and transfers.