SDK Overview

The AuthForge SDK handles license validation, HWID fingerprinting, cryptographic signature verification, the grace period, and optional online check-ins.

​

Available SDKs

​

Official installs

​

How it works

All SDKs implement the same flow:

1. Initialize: Create a client with your App ID and public key. Include the App Secret for online login() / validateLicense. For air-gapped loginFromFile only, omit the secret (or pass empty / None); do not ship it in offline binaries.
2. Login or validate-only: Call login(licenseKey) (or Login, etc.) for a long-lived session: the SDK collects the machine’s HWID (or uses hwidOverride), generates a nonce, and sends /auth/validate. For bots, cron, or per-request checks, use the validate-only API (validateLicense in Node, validate_license in Python and Rust, ValidateLicense in C# / C++ / Go): same request and signature verification, no background loop and no persisted session on the client (C++ returns a result struct; others match their login result shape or a dedicated result type).
3. Verify the validate response: The SDK verifies the Ed25519 signature on /auth/validate using your app’s configured publicKey.
4. Grace period: After login, the app runs on the signed session with no further network calls. A background thread re-verifies the session signature locally and stops when the session expires (session TTL: default 24 hours, configurable via ttlSeconds, clamped to 1 hour minimum and 7 days maximum). Expiry is reported to onFailure as session_expired; the Rust SDK reports it as AuthForgeError::Expired (expired) until its next major release.
5. Online check-ins (optional): Enable onlineHeartbeat to send POST /auth/heartbeat at the configured interval (default 15 minutes) for fast revocation and concurrent-use detection. Success responses are Ed25519-signed and verified with the same app public key, and each check-in refreshes the session. Validate-only calls never start this loop.
6. Failure: If authentication fails, a check-in fails, or the session expires, the SDK calls your onFailure callback with a reason ("login_failed" or "heartbeat_failed") and the exception (Go: OnHeartbeatFailure or legacy OnFailure; Rust: on_heartbeat_failure or legacy on_failure). Since 1.4.0 the error carries the code and a transient/definitive classification. On a definitive failure (revoked, expired, hwid_mismatch, blocked, session_expired, …) the SDK clears the stored session and stops check-ins before the callback runs; on a transient one (network errors, rate_limited, system_error, no_credits, unexpected_response, …) it keeps the session and checks in again on the next interval, until the session TTL runs out. If no callback is set (1.4.1+), a transient background check failure writes a one-line warning to stderr and check-ins continue in every SDK; a definitive failure (including the session_expired a transient failure becomes once the TTL has passed) or a rejected login exits the process in the Python, Node.js, C#, and C++ SDKs, while Go and Rust clear the session and never exit. See Check-in and session failure handling.

​

Offline license files (separate mode)

For machines that can never reach AuthForge, every SDK (1.2.0+) also verifies cloud-minted offline license files (.authforge) with zero network access. This is not a variant of the grace period; it is a different credential: The customer should not type the HWID into an email. Prefer an activation request (.authforge-request): the SDK writes it with no network and no app secret, and the dashboard checksums it in the browser before prefilling the mint dialog. machineName is omitted unless the caller opts in (include_machine_name / includeMachineName). This is not a second offline product and it is not the grace period. loginFromFile verifies the file against the client’s configured app id, public key(s) and HWID, then populates the same session accessors as login() (isAuthenticated, variables). It never starts the grace-period timer or online check-ins, and it never exits the process; rejections arrive as onFailure("offline_login_failed", error) with one of bad_armor, bad_signature, unsupported_version, malformed_payload, wrong_app, expired, hwid_mismatch (Go returns ErrOffline* sentinels, Rust an OfflineLicenseError enum). Online login() and the grace period are unchanged. Air-gapped builds should omit the App Secret: loginFromFile does not use it; online APIs still require it and fail locally if it is missing.

​

Common constructor parameters

Every SDK accepts the same conceptual parameters, named according to each language’s conventions. The table below shows the logical parameter names; see each SDK’s page for exact syntax.

​

Billing model

All SDKs follow the same billing rules:

• Each successful login() / Login() or validateLicense-style call costs 1 credit (one /auth/validate debit).
• The grace period is free: local session re-verification consumes no credits.
• Online check-ins (if enabled) cost 1 credit per 10 successful heartbeats (debited on every 10th heartbeat).
• With online check-ins, revocations take effect on the next check-in regardless of the configured interval; without them, at session expiry.
• Minting an offline license file costs 1 credit (charged to the operator at mint time). loginFromFile / verifyLicenseFile cost nothing.

See Managing Credits for usage estimates and cost-saving patterns.

​

Migrating from heartbeat_mode

Older SDK versions required a heartbeatMode / heartbeat_mode of "SERVER" or "LOCAL". Cached GitHub README snippets still show that required constructor; current docs and current SDKs use the grace-period model. Follow docs.authforge.cc and check the installed SDK version before copying examples. The option is deprecated across all SDKs:

• "LOCAL": remove the option; the grace period is now the default behavior.
• "SERVER": enable online check-ins instead (onlineHeartbeat: true or the language equivalent).

The old option still works but emits a deprecation warning. See each SDK page for the exact migration syntax. Do not pass heartbeatMode in new code.

​

Next steps

• Choose your SDK: Python, C#, C++, Rust, Go, or Node.js
• Read the SDK Best Practices for error handling, grace-period behavior, and UX guidance