AuthForge Go SDK

Official Go SDK for AuthForge. Activate a license online with an Ed25519-verified response, then run through the grace period by default (no further network calls), or opt in to online check-ins for fast revocation.

Zero external dependencies. Uses only the Go standard library.

How licensing works

Activate (validate) online. Login calls POST /auth/validate. The server checks revocation, expiry, HWID slots, and credits, and returns an Ed25519-signed session with a TTL.
Grace period (the default). After activation, the app keeps running on the signed session without contacting AuthForge. The SDK periodically re-verifies the signed session locally and fails with ErrSessionExpired when the TTL expires. The grace period equals the session TTL: default 24h, and the server clamps requested values to [1h, 7d] (set it with SessionTTL).
Online check-ins (optional). Set OnlineHeartbeat: true to call POST /auth/heartbeat periodically. This gives you fast revocation and concurrent-use detection: a revoked license fails on the very next check-in instead of at the end of the grace period.

Separately, for machines that can never reach the internet, an operator can mint a signed offline license file (.authforge) in the AuthForge dashboard or Developer API. The SDK verifies it locally with your app public key: see Offline license files.

Features

Everything in this list ships in authforge.go, crypto.go, hwid.go, and offline.go today:

License activation via POST /auth/validate, returning a signed LoginResult.
Ed25519 signature verification on every /auth/validate and /auth/heartbeat response; tampered or unsigned responses are rejected.
Key rotation: configure PublicKey (single key or comma-separated string) and/or PublicKeys (rotation set). The SDK trusts a signature that matches any configured key, so you can roll the server-side signing key without breaking deployed clients.
Nonce anti-replay: a fresh 128-bit nonce is sent on every request and the echoed nonce in the signed payload is checked before the response is accepted.
HWID fingerprinting: deterministic device hash from hostname + OS + arch + MAC, with graceful fallback.
HWIDOverride: bind to any identity instead of the machine (for example tg:<id>, discord:<id>).
Seat enforcement: the server binds each HWID into a license's free slots up to maxHwidSlots; HwidCount / MaxHwidSlots are surfaced on LoginResult. A shared (unlimited-seat) key skips per-device binding.
Grace period by default, online check-ins opt-in (see Grace period and online check-ins).
Offline license files (.authforge): LoginFromFile / VerifyLicenseFile verify a cloud-minted, Ed25519-signed file with zero network access for air-gapped machines.
Self-ban (SelfBan(...)) for anti-tamper response, both pre-session and post-session.
Grace period duration control via SessionTTL, with server-side clamping to [1h, 7d].
App variables / license variables for feature flags and tiered licensing.
Automatic retries for rate-limited and transient network failures, with a fresh nonce per retry.
Returns errors instead of exiting: unlike the Python/Node/C#/C++ SDKs, the Go SDK never calls os.Exit; Login/ValidateLicense return errors and background failures are reported through OnFailure.

Installation

The module is github.com/AuthForgeCC/authforge-go. With a released version tag on GitHub, add it like any other public module:

go get github.com/AuthForgeCC/authforge-go@v1.3.1

Pin a v1.x.y tag you have pushed (for example @v1.3.1). Without an @ suffix, go get resolves @latest once the proxy has indexed the tag.

Local module with `replace` (forks, air-gapped builds, or hacking on the SDK)

Clone this repository somewhere on your machine (for example next to your application).
In your application's go.mod, require the module path and add a replace to your local checkout:

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

Adjust ../path/to/authforge-go to the real path, then run go mod tidy.

Copy source into your project

You can vendor authforge.go, hwid.go, crypto.go, and related files into your tree (for example under internal/authforge/) and adjust import paths if you change the module path. Prefer go get when possible.

Quick start

The quick start below assumes go get (or a replace pointing at a local clone) is configured as in Installation. It activates online once, then runs through the grace period (no further network calls):

package main

import (
	"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 {
		fmt.Fprintf(os.Stderr, "Login failed: %v\n", err)
		os.Exit(1)
	}

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

To enable online check-ins instead, add OnlineHeartbeat: true (and optionally tune HeartbeatInterval).

Config

Field	Type	Default	Description
`AppID`	`string`	required	App ID from dashboard
`AppSecret`	`string`	required for online APIs; empty for `LoginFromFile` only	App secret from dashboard. Do not ship it in air-gapped binaries.
`PublicKey`	`string`	required*	App Ed25519 public key (base64) from dashboard. Accepts a comma-separated trust list. *Required unless `PublicKeys` is set.
`PublicKeys`	`[]string`	optional	Rotation set of trusted Ed25519 public keys. When non-empty, takes precedence over `PublicKey`; the SDK trusts a signature matching any entry (see Key rotation).
`OnlineHeartbeat`	`bool`	`false`	Enables online check-ins: periodic `POST /auth/heartbeat` for fast revocation and concurrent-use detection. When `false`, the SDK relies on the grace period.
`HeartbeatMode`	`string`	`""`	Deprecated, see Migrating from HeartbeatMode. Empty means the default grace period behavior; `"server"` maps to `OnlineHeartbeat: true`; `"local"` maps to the default.
`HeartbeatInterval`	`time.Duration`	`15 * time.Minute`	Interval between background checks (online check-ins or local grace period re-verification). Minimum supported interval is `10 * time.Second`; pick based on how fast you want revocations to propagate.
`APIBaseURL`	`string`	`https://auth.authforge.cc`	API base URL override
`OnFailure`	`func(error string)`	`nil`	Called when a background check fails
`RequestTimeout`	`time.Duration`	`15 * time.Second`	HTTP timeout per request
`SessionTTL`	`time.Duration`	`0` (server default: 24h)	The grace period duration: requested session token lifetime. Server clamps to `[1h, 7d]`; out-of-range values are silently clamped. Online check-ins refresh the session while preserving the requested TTL.
`HWIDOverride`	`string`	`""`	Optional custom hardware/subject identifier. When non-empty, the SDK sends this value instead of generated device fingerprint data.

Identity-based binding example (Telegram/Discord)

client, err := authforge.New(authforge.Config{
    AppID:           "YOUR_APP_ID",
    AppSecret:       "YOUR_APP_SECRET",
    PublicKey:       "YOUR_PUBLIC_KEY",
    OnlineHeartbeat: true,
    HWIDOverride:    fmt.Sprintf("tg:%d", telegramUserID), // or fmt.Sprintf("discord:%d", discordUserID)
})

Key rotation

To rotate the server-side signing key without a flag-day, configure both the new and previous keys; the SDK accepts a signature matching any entry:

client, err := authforge.New(authforge.Config{
    AppID:      "YOUR_APP_ID",
    AppSecret:  "YOUR_APP_SECRET",
    PublicKeys: []string{"NEW_PUBLIC_KEY", "PREVIOUS_PUBLIC_KEY"},
})

A comma-separated PublicKey ("NEW,PREVIOUS") works too, for env-var convenience.

Grace period and online check-ins

Grace period (the default). After one successful online activation, the app keeps running on the signed session without contacting AuthForge. The SDK re-verifies the cached signed payload locally on every HeartbeatInterval tick and fails with ErrSessionExpired once the session TTL elapses. The grace period equals the session TTL: default 24h, server-clamped to [1h, 7d] (set with SessionTTL). This is session continuation, not persistent offline licensing: a mid-session revocation only takes effect at the next online activation.

Online check-ins (OnlineHeartbeat: true). The SDK sends POST /auth/heartbeat on every interval. Revocation and concurrent-use detection take effect on the very next check-in, and each successful check-in refreshes the session.

Offline license files (`.authforge`)

For machines that never connect to the internet, the operator mints a signed offline license file in the AuthForge dashboard (License page -> Mint .authforge file) or via POST /v1/licenses/{licenseKey}/offline-files. The file is a standalone Ed25519-signed document; the SDK verifies it with only your app public key and the machine HWID. It never contacts AuthForge and never starts online check-ins. Leave AppSecret empty so the air-gapped binary does not contain the App Secret.

	Grace period (default)	Offline license file
Needs network	Once, at `Login`	Never on the end machine
What is verified	Signed session from `/auth/validate`	Signed document minted in the cloud
Lifetime	Session TTL: 1h to 7d	Operator-chosen expiry or lifetime (perpetual licenses only)
Revocation	Picked up at the next online validate / check-in	Not reachable: the file stays valid until its own expiry
Cost	1 credit per `Login`	1 credit per mint; verifying is free

client, err := authforge.New(authforge.Config{
	AppID:     "YOUR_APP_ID",
	PublicKey: "YOUR_PUBLIC_KEY",
	OnFailure: func(msg string) { log.Println("authforge:", msg) },
})
if err != nil {
	log.Fatal(err)
}

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

// 2. Later, authorize from the minted file (path or armored text). No network.
lic, err := client.LoginFromFile("license.authforge")
if err != nil {
	switch {
	case errors.Is(err, authforge.ErrOfflineExpired):
		log.Fatal("offline license expired - ask the operator for a new file")
	case errors.Is(err, authforge.ErrOfflineHwidMismatch):
		log.Fatal("this file is bound to a different machine")
	default:
		log.Fatal(err)
	}
}
fmt.Println("Offline license OK; expires:", lic.ExpiresAt) // nil pointer = lifetime
fmt.Println(client.LicenseVariables())

Collect the HWID from the same SDK build that will load the file: fingerprints are not portable across SDKs or languages. After LoginFromFile, GetSessionKind() returns SessionKindOffline (SessionKindOnline after Login, SessionKindNone when logged out).

authforge.VerifyLicenseFile(text, opts) (package function) and client.VerifyLicenseFile(pathOrText) perform the same checks without touching client state. Errors are sentinels for errors.Is, in check order: ErrOfflineBadArmor, ErrOfflineBadSignature, ErrOfflineUnsupportedVersion, ErrOfflineMalformedPayload, ErrOfflineWrongApp, ErrOfflineExpired, ErrOfflineHwidMismatch; authforge.OfflineErrorCode(err) maps them to the cross-SDK codes. LoginFromFile also reports offline_login_failed: <code> through OnFailure.

File format (version 1): PEM-style armor with informational headers, a base64 JSON payload (v, appId, licenseKey, jti, kid, issuedAt, expiresAt, hwid policy, optional label/variable snapshots) and a detached Ed25519 signature over the UTF-8 bytes of the base64 payload string - the same contract as /auth/validate. See offline_license_vectors.json for conformance vectors.

Migrating from HeartbeatMode

Config.HeartbeatMode is deprecated but still works:

HeartbeatMode: "local" maps to the default grace period behavior. Remove the field.
HeartbeatMode: "server" maps to online check-ins. Replace it with OnlineHeartbeat: true.
An empty HeartbeatMode is now valid and means the default grace period behavior.
Any other value still returns an error from New.
If both fields are set, either one enables online check-ins: HeartbeatMode: "server" is not overridden by OnlineHeartbeat: false.

// Before:
authforge.Config{ /* ... */ HeartbeatMode: "server"}
// After:
authforge.Config{ /* ... */ OnlineHeartbeat: true}

// Before:
authforge.Config{ /* ... */ HeartbeatMode: "local"}
// After (grace period is the default):
authforge.Config{ /* ... */ }

Billing

1 Login or ValidateLicense call = 1 credit (one /auth/validate debit each).
10 online check-ins on the same license = 1 credit (debited every 10th successful check-in). The grace period costs nothing after activation.

This means a session-style app running for 6 hours at a 15-minute check-in interval burns ~1 validation + ~24 check-ins = ~3.4 credits/day. /auth/heartbeat is limited to 6 requests/minute per license key, so keep intervals at 10 seconds or higher and choose cadence based on revocation speed needs (they always land on the next check-in).

Methods

Method	Returns	Description
`Login(licenseKey string)`	`(*LoginResult, error)`	Activates the key online and stores the signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`)
`ValidateLicense(licenseKey string)`	`(*LoginResult, error)`	Same `/auth/validate` + signatures as `Login`; does not persist session or start background checks; does not invoke `OnFailure` for validate or network errors
`SelfBan(...)`	`(map[string]interface{}, error)`	Requests `/auth/selfban` to blacklist HWID/IP and optionally revoke (session-authenticated only)
`LoginFromFile(pathOrText string)`	`(*OfflineLicense, error)`	Authorizes from an offline `.authforge` file with no network; never starts background checks; errors are `ErrOffline*` sentinels and are echoed to `OnFailure` as `offline_login_failed: <code>`
`VerifyLicenseFile(pathOrText string)`	`(*OfflineLicense, error)`	Verifies a `.authforge` file with this client's app id / keys / HWID without changing state
`OfflineLicense()`	`*OfflineLicense`	The offline file in use (`JTI`, `ExpiresAt`, `HwidPolicy`, …) or `nil`
`GetSessionKind()`	`SessionKind`	`SessionKindOnline`, `SessionKindOffline`, or `SessionKindNone` when logged out
`HWID()`	`string`	The HWID this client sends (or `HWIDOverride`); customers share it to receive a bound file
`CreateActivationRequest(opts ActivationRequestOptions)`	`string`	Unsigned `.authforge-request` for this machine. No network, no secret. Hostname omitted unless `IncludeMachineName`
`Logout()`	`void`	Stops background checks and clears all session/auth state
`IsAuthenticated()`	`bool`	True when an active authenticated session exists
`GetSessionData()` / `SessionData()`	`map[string]interface{}`	Full decoded payload map
`GetAppVariables()` / `AppVariables()`	`map[string]interface{}`	App-scoped variables map
`GetLicenseVariables()` / `LicenseVariables()`	`map[string]interface{}`	License-scoped variables map

Error handling

The SDK returns errors instead of panicking. Common failure cases are exposed as sentinel errors:

if err != nil {
	switch {
	case errors.Is(err, authforge.ErrInvalidApp):
		// app credentials are invalid
	case errors.Is(err, authforge.ErrInvalidKey):
		// license key is invalid
	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):
		// account has no credits
	case errors.Is(err, authforge.ErrAppBurnCapReached):
		// app credit burn cap reached
	case errors.Is(err, authforge.ErrBlocked):
		// blocked by security rules
	case errors.Is(err, authforge.ErrRateLimited):
		// request was rate limited
	case errors.Is(err, authforge.ErrReplayDetected):
		// nonce replay detected
	case errors.Is(err, authforge.ErrAppDisabled):
		// app disabled
	case errors.Is(err, authforge.ErrSessionExpired):
		// session expired (grace period ended)
	case errors.Is(err, authforge.ErrRevokeRequiresSession):
		// attempted pre-session revoke
	case errors.Is(err, authforge.ErrBadRequest):
		// bad_request or malformed_request
	case errors.Is(err, authforge.ErrServerError):
		// system_error or server_error
	case errors.Is(err, authforge.ErrSignatureMismatch):
		// response signature mismatch
	default:
		// transport or unknown error
	}
}

ValidateLicense returns the same error types as Login but does not call OnFailure for failed validate or network errors (background checks still use OnFailure on failure).

Internal request retries are automatic:

rate_limited: retry after 2s, then 5s (max 3 attempts total)
network failure: retry once after 2s
retry attempts always use a fresh nonce

Self-ban (tamper response)

Use SelfBan(...) when anti-tamper checks trigger:

// Post-session (authenticated): defaults are typically all true in caller logic.
_, err = client.SelfBan("", "", true, true, true)

// Pre-session: pass license key, SDK automatically forces revokeLicense=false.
_, err = client.SelfBan("AF-XXXX-XXXX-XXXX", "", true, true, true)

// Explicit flags:
_, err = client.SelfBan("", "", false, true, true)

SelfBan(...) selects mode automatically:

Uses post-session mode when a session token is available (sessionToken argument or current SDK session).
Falls back to pre-session mode with licenseKey + nonce + app secret.
In pre-session mode, revoke is always disabled client-side to avoid unsafe key revocations.
Not available after LoginFromFile: offline sessions have no server session, so SelfBan with no explicit licenseKey / sessionToken returns ErrOfflineSession without contacting the server.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
activation_request_vectors.json		activation_request_vectors.json
authforge.go		authforge.go
authforge_test.go		authforge_test.go
crypto.go		crypto.go
go.mod		go.mod
hwid.go		hwid.go
offline.go		offline.go
offline_license_vectors.json		offline_license_vectors.json
offline_test.go		offline_test.go
test_vectors.json		test_vectors.json

Navigation Menu

Uh oh!

Repository files navigation

AuthForge Go SDK

How licensing works

Features

Installation

Local module with `replace` (forks, air-gapped builds, or hacking on the SDK)

Copy source into your project

Quick start

Config

Identity-based binding example (Telegram/Discord)

Key rotation

Grace period and online check-ins

Offline license files (`.authforge`)

Migrating from HeartbeatMode

Billing

Methods

Error handling

Self-ban (tamper response)

License

About

Releases

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

AuthForge Go SDK

How licensing works

Features

Installation

Local module with replace (forks, air-gapped builds, or hacking on the SDK)

Copy source into your project

Quick start

Config

Identity-based binding example (Telegram/Discord)

Key rotation

Grace period and online check-ins

Offline license files (.authforge)

Migrating from HeartbeatMode

Billing

Methods

Error handling

Self-ban (tamper response)

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages

Local module with `replace` (forks, air-gapped builds, or hacking on the SDK)

Offline license files (`.authforge`)