Requirements
- .NET 6.0 or later
BouncyCastle.Cryptography(pulled in transitively with the AuthForge package)
Installation
Add the AuthForge package from NuGet:Prefer a source-only layout? Copy
AuthForgeClient.cs, AuthForgeClient.Offline.cs, and AuthForgeException.cs from GitHub and reference BouncyCastle.Cryptography explicitly. The NuGet package is recommended for most apps.Quick start
Constructor parameters
ttlSeconds (grace period)
Requested session token lifetime in seconds for /auth/validate. This is the grace period: how long the app keeps running on the signed session without contacting AuthForge. Pass null (or omit) to accept the server default of 24 hours. The server clamps to [3600, 604800] (1 hour to 7 days). The requested TTL is preserved across heartbeat refreshes, and apps relying on the grace period alone can extend their window up to 7 days.
Billing
- Each successful
Login()orValidateLicense()costs 1 credit (one/auth/validatedebit). - 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.
- A new self-serve offline activation (
ActivateOffline) costs 2 credits; activating the same machine again is free.
Login
true if authentication succeeded, false otherwise. On success, the SDK starts a background thread that re-verifies the signed session locally during the grace period (and sends online check-ins if onlineHeartbeat: true).
Validate license (no session)
/auth/validate request and verification as Login, without updating the client’s session fields or starting the background thread.
Failure callback
If authentication fails, an online check-in fails, or the session expires, the SDK calls yourOnFailure callback. Returning normally from the callback keeps the process running; if the callback throws, the SDK calls Environment.Exit(1). Without a callback (1.4.1+), a transient background check failure writes AuthForge: background check failed (<code>); retrying next interval to stderr and check-ins continue; every other failure (a failed Login, a definitive check-in answer, the grace period running out) calls Environment.Exit(1).
Check-in failures (1.4.0+)
Background check failures (online check-ins and the end of the grace period) reachonFailure("heartbeat_failed", ex), where ex is an AuthForgeException:
ex.Code: the server’s error code from the response body, whatever the HTTP status, or an SDK code:network_error,timeout,http_error_<status>(non-JSON error body),invalid_json_response,unexpected_response,signature_mismatch,nonce_mismatch, … For server codesex.Messageequals the code; network failures keep theurl_error: ...message. Codes this SDK version doesn’t know are passed through unchanged.ex.IsTransient/ex.IsFatal: the classification.AuthForgeClient.IsTransientError(code)is the same check, andAuthForgeClient.DefinitiveErrorCodeslists the fatal codes.
unexpected_response means a failed check-in body was not a well-formed AuthForge error ({"status":"failed","error":"<code>"}), for example a proxy or captive portal answering instead of AuthForge; the message includes the raw status and error values.
Request retries are automatic: rate_limited (or HTTP 429 with no error code) is retried after 2s, then 5s; HTTP 429 with no_credits, app_burn_cap_reached, or demo_quota_exceeded is not retried and waits for the next interval; a network failure is retried once after 2s. Network failures are reported once, with code network_error or timeout: as heartbeat_failed from check-ins and, since 2.0.0, as login_failed from Login() (never as a separate network_error reason). SelfBan() and ActivateOffline() throw them as AuthForgeException instead and never call OnFailure.
Thread safety: onFailure for heartbeat_failed runs on the background thread with no SDK lock held. Calling Logout(), IsAuthenticated(), or Login() from it is safe; Logout() signals the thread to stop and never waits for it. A check-in response that arrives after Logout() or a new Login() is discarded, so it cannot restore the old session.
To tolerate short outages but shut down on a definitive answer, have the callback signal your main thread and let the main thread save and exit:
form.BeginInvoke(...) or Dispatcher.InvokeAsync(...)) and close the main window normally, as in the full example. Calling Environment.Exit(1) inside onFailure is a last resort: finally blocks on other threads do not run and unsaved state is lost, so save the user’s work first.
Reading variables
After a successful login, app variables and license variables are available: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: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. Pass appSecret: "" so the air-gapped binary does not contain the App Secret.
onFailure("offline_login_failed", new ArgumentException(code)) and return false (never Environment.Exit). Codes, in check order: bad_armor, bad_signature, unsupported_version, malformed_payload, wrong_app, expired, hwid_mismatch. client.VerifyLicenseFile(pathOrText) and the static AuthForgeClient.VerifyLicenseFile(text, appId, publicKeys, hwid) run the same checks without touching state. Issued files cannot be revoked remotely; they stay valid until their own expiry. CreateActivationRequest() produces the .authforge-request the operator uploads; hostname is omitted unless IncludeMachineName is set. See Activation requests.
Migrating from heartbeatMode
The legacy string heartbeatMode constructor is marked obsolete but still works:
heartbeatMode: "LOCAL": remove the argument; the grace period is now the default.heartbeatMode: "SERVER": useonlineHeartbeat: trueinstead.
Self-serve offline activation
client.ActivateOffline(licenseKey, path) turns a license key into a lifetime .authforge file bound to this machine, with one online call to POST /auth/offline/activate. After that the app starts with LoginFromFile and never needs the network. Use it for one-time-purchase apps that should run offline forever. See Self-serve activation and the walkthrough Sell offline apps.
- Needs the App Secret. Pass
appSecretto the constructor (air-gapped builds pass""). A missing secret or empty key throwsArgumentExceptionbefore any request. - Your app must opt in (off by default), and the license must be perpetual and seat-limited.
- The SDK sends the same HWID as
login, verifies the returned file (signature, app id, this machine’s HWID) before saving it, writes it to the path atomically (creating parent folders), and leaves the client in an offline session exactly as afterLoginFromFile: variables available, no grace-period timer, no check-ins. - Billing: 2 credits per new machine (one validation plus one mint), charged to you. The same machine activating again gets the identical file back for free. Every refusal is free.
- A license can activate at most
maxHwidSlotsdistinct machines, ever. HWID resets do not free machine slots. - A refund or chargeback revokes the license online but cannot reach files already issued. For a lifetime file, that means the buyer keeps the app.
AuthForgeException: ex.Code is the code and ex.IsFatal / ex.IsTransient the classification. The codes are the server’s (offline_activation_disabled, offline_activation_requires_perpetual, offline_activation_requires_seats, offline_activation_limit_reached, hwid_mismatch when no seat is free, invalid_key, revoked, no_credits, rate_limited, …) or the SDK’s: offline_file_rejected (fatal; the server’s file failed local verification, reason in the message) and file_write_failed (transient; the file could not be written, and calling again returns the same file for free). The method never calls onFailure and never exits the process; nothing is written on failure and any existing session is left alone. On offline_activation_limit_reached, tell the user to contact you. Messages to show: Self-serve activation errors.
LoginFromFile can report a missing or rejected file to onFailure as offline_login_failed. If you set a callback, return normally for that reason so the app reaches the key prompt.