Go SDK - AuthForge

Requirements

Go 1.21 or later
No external dependencies (standard library only)

Installation

The module path is github.com/AuthForgeCC/authforge-go. Install the latest release:

go get github.com/AuthForgeCC/authforge-go@latest

To pin a specific version, replace @latest with a v1.x.y tag. Imports always use github.com/AuthForgeCC/authforge-go. Run go mod tidy after editing go.mod.

Local replace (forks / air-gap)

module example.com/myapp

go 1.21

require github.com/AuthForgeCC/authforge-go v0.0.0

replace github.com/AuthForgeCC/authforge-go => ../path/to/authforge-go

Point replace at a directory that contains the SDK’s go.mod, then run go mod tidy.

Quick start

package main

import (
	"errors"
	"fmt"
	"os"

	"github.com/AuthForgeCC/authforge-go"
)

func main() {
	client, err := authforge.New(authforge.Config{
		AppID:     "YOUR_APP_ID",
		AppSecret: "YOUR_APP_SECRET",
		PublicKey: "YOUR_PUBLIC_KEY",
		OnFailure: func(errMsg string) {
			fmt.Fprintf(os.Stderr, "Auth failed: %s\n", errMsg)
			os.Exit(1)
		},
	})
	if err != nil {
		panic(err)
	}

	result, err := client.Login("XXXX-XXXX-XXXX-XXXX")
	if err != nil {
		switch {
		case errors.Is(err, authforge.ErrInvalidKey):
			fmt.Fprintln(os.Stderr, "Invalid license key.")
		default:
			fmt.Fprintf(os.Stderr, "Login failed: %v\n", err)
		}
		os.Exit(1)
	}

	fmt.Printf("Authenticated! Expires: %d\n", result.ExpiresIn)
	select {}
}

Config reference

client, err := authforge.New(authforge.Config{
	AppID:             "YOUR_APP_ID",              // Required
	AppSecret:         "YOUR_APP_SECRET",          // Required for online Login/ValidateLicense; omit for LoginFromFile only
	PublicKey:         "YOUR_PUBLIC_KEY",          // Required - Ed25519 public key from your AuthForge dashboard (base64)
	OnlineHeartbeat:   false,                      // Optional: true enables periodic online check-ins (/auth/heartbeat)
	HeartbeatInterval: 15 * time.Minute,           // Optional: background timer cadence (check-ins when online, local session checks otherwise)
	APIBaseURL:        "https://auth.authforge.cc",// Optional
	OnFailure:         nil,                        // Optional: func(error string)
	RequestTimeout:    15 * time.Second,           // Optional
	SessionTTL:        0,                          // Optional: time.Duration. Grace period. 0 = server default (24h). Clamped to [1h, 7d].
	HWIDOverride:      "",                         // Optional: custom identity (for example "tg:123456789")
})

`SessionTTL` (grace period)

Requested lifetime of the session token returned by /auth/validate. This is the grace period: how long the app keeps running on the signed session without contacting AuthForge. Leave at 0 to accept the server default (24 hours). The server clamps the final value to [1h, 7d]. The requested TTL is preserved across heartbeat refreshes, and apps relying on the grace period alone can extend their window up to 7 days:

client, _ := authforge.New(authforge.Config{
	AppID:      "...",
	AppSecret:  "...",
	PublicKey:  "YOUR_PUBLIC_KEY",
	SessionTTL: 72 * time.Hour, // 3-day grace period
})

Billing

Each successful Login() or ValidateLicense() costs 1 credit (one /auth/validate debit).
The grace period is free: local session re-verification makes no network calls and consumes no credits.
Online check-ins (if enabled) cost 1 credit per 10 successful heartbeats (billed on every 10th call).
With online check-ins, revocations take effect on the next check-in regardless of interval; without them, at session expiry.

Validate license (no session)

ValidateLicense performs the same /auth/validate request and signature verification as Login, but does not persist session fields on the client, start the background goroutine, or invoke OnFailure for validate failures (network errors still return an error; repeated network failure does not call OnFailure when using ValidateLicense). The SDK recognizes AUTHFORGE_SDK_TEST_NONCE for integration tests only; never set it in production (it pins the validate nonce).

Methods reference

result, err := client.Login(licenseKey)
result, err = client.ValidateLicense(licenseKey) // same validate + signatures, no background loop / session persistence
client.Logout()
ok := client.IsAuthenticated()
session := client.SessionData()
appVars := client.AppVariables()
licenseVars := client.LicenseVariables()

Login and ValidateLicense return a LoginResult with:

SessionToken
ExpiresIn
AppVariables
LicenseVariables
RequestID

Error handling

The Go SDK exposes sentinel errors so you can branch with errors.Is:

if err != nil {
	switch {
	case errors.Is(err, authforge.ErrInvalidApp):
		// invalid app credentials
	case errors.Is(err, authforge.ErrInvalidKey):
		// invalid key
	case errors.Is(err, authforge.ErrExpired):
		// license expired
	case errors.Is(err, authforge.ErrRevoked):
		// license revoked
	case errors.Is(err, authforge.ErrHwidMismatch):
		// HWID slots full
	case errors.Is(err, authforge.ErrNoCredits):
		// no credits
	case errors.Is(err, authforge.ErrBlocked):
		// blocked
	case errors.Is(err, authforge.ErrRateLimited):
		// rate limited (validate: per IP / per license; heartbeat: 6/min per license)
	case errors.Is(err, authforge.ErrReplayDetected):
		// replay detected (validate only)
	case errors.Is(err, authforge.ErrSignatureMismatch):
		// signature verification failed
	default:
		// transport or unexpected error
	}
}

Grace period and online check-ins

By default, the app runs through the grace period after activation: the SDK re-verifies the signed session locally, makes no network calls, and stops when the session expires. Opt in to online check-ins for fast revocation and concurrent-use detection:

// Default: activate online, then run through the grace period (24h by default)
client, _ := authforge.New(authforge.Config{
	AppID:     "...",
	AppSecret: "...",
	PublicKey: "YOUR_PUBLIC_KEY",
})

// Strict policy: periodic online check-ins for fast revocation
client, _ := authforge.New(authforge.Config{
	AppID:           "...",
	AppSecret:       "...",
	PublicKey:       "YOUR_PUBLIC_KEY",
	OnlineHeartbeat: true,
})

See Online Check-ins for a detailed comparison.

Offline license files (`.authforge`)

For machines that never connect to the internet, the operator mints a signed offline license file in the dashboard or Developer API (1 credit). The SDK verifies it locally with your public key and the machine HWID; no network, no check-ins, and online Login is untouched. Leave AppSecret empty so the air-gapped binary does not contain the App Secret.

client, _ := authforge.New(authforge.Config{AppID: "APP_ID", PublicKey: "PUBLIC_KEY"})

// Step 1 (customer machine): write an activation request the operator drops into the mint dialog.
request := client.CreateActivationRequest(authforge.ActivationRequestOptions{})

// Step 2 (customer machine, after you deliver the file): path or armored text.
lic, err := client.LoginFromFile("license.authforge")
switch {
case errors.Is(err, authforge.ErrOfflineExpired):
	log.Fatal("offline license expired - request a new file")
case errors.Is(err, authforge.ErrOfflineHwidMismatch):
	log.Fatal("this file is bound to a different machine")
case err != nil:
	log.Fatal(err)
}
fmt.Println("Offline license valid until", lic.ExpiresAt) // nil pointer = lifetime

Errors are sentinels for errors.Is, in check order: ErrOfflineBadArmor, ErrOfflineBadSignature, ErrOfflineUnsupportedVersion, ErrOfflineMalformedPayload, ErrOfflineWrongApp, ErrOfflineExpired, ErrOfflineHwidMismatch; authforge.OfflineErrorCode(err) returns the cross-SDK string and OnFailure receives offline_login_failed: <code>. client.VerifyLicenseFile(pathOrText) and the package function authforge.VerifyLicenseFile(text, opts) run the same checks without touching state. Issued files cannot be revoked remotely; they stay valid until their own expiry. CreateActivationRequest(opts) produces the .authforge-request the operator uploads; hostname is omitted unless IncludeMachineName is set. See Activation requests.

Migrating from `HeartbeatMode`

HeartbeatMode ("server" / "local") is deprecated and may now be left empty:

HeartbeatMode: "local": remove the field; the grace period is now the default.
HeartbeatMode: "server": use OnlineHeartbeat: true instead.

The old field still works but is deprecated.

GitHub

Source, releases, and issues: AuthForgeCC/authforge-go.

​Requirements

​Installation

​Quick start

​Config reference

​SessionTTL (grace period)

​Billing

​Validate license (no session)

​Methods reference

​Error handling

​Grace period and online check-ins

​Offline license files (.authforge)

​Migrating from HeartbeatMode

​GitHub