C++ SDK - AuthForge

Requirements

C++17 or later
libsodium: Ed25519 signature verification
OpenSSL: SHA-256 and helpers
libcurl: HTTPS requests

Installation

There is no central C++ package registry. Consume the official SDK from GitHub; AuthForgeCC/authforge-cpp (use a release tag under Releases).

Option A: `FetchContent` (CMake)

Pin a tag (for example v1.0.1) and link the authforge_sdk target:

include(FetchContent)
FetchContent_Declare(
  authforge_cpp
  GIT_REPOSITORY https://github.com/AuthForgeCC/authforge-cpp.git
  GIT_TAG v1.0.1
)
FetchContent_MakeAvailable(authforge_cpp)

target_link_libraries(your_app PRIVATE authforge_sdk)

Option B: Install prefix + `find_package`

Build and install the SDK, then point CMake at the prefix:

git clone https://github.com/AuthForgeCC/authforge-cpp.git
cd authforge-cpp
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=../authforge-install
cmake --build build
cmake --install build

In your application:

list(APPEND CMAKE_PREFIX_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../authforge-install")
find_package(AuthForge CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE AuthForge::authforge_sdk)

Dependencies

Install development packages for libsodium, OpenSSL, and libcurl before configuring CMake. Examples:

Linux (Debian/Ubuntu): sudo apt install libsodium-dev libssl-dev libcurl4-openssl-dev
macOS (Homebrew): brew install libsodium openssl curl; set CMAKE_PREFIX_PATH if CMake does not find Homebrew prefixes.
Windows: Use vcpkg for libsodium, openssl, and curl, then pass -DCMAKE_TOOLCHAIN_FILE=.../vcpkg.cmake.

Quick start

#include "authforge_sdk.h"
#include <iostream>
#include <string>

int main() {
    authforge::AuthForgeClient client(
        "YOUR_APP_ID",
        "YOUR_APP_SECRET",
        "YOUR_PUBLIC_KEY"
    );

    std::string key;
    std::cout << "Enter license key: ";
    std::getline(std::cin, key);

    if (client.Login(key)) {
        std::cout << "Authenticated!" << std::endl;
        // Your app logic here; the signed session covers the grace period
    } else {
        std::cout << "Invalid license key." << std::endl;
        return 1;
    }

    return 0;
}

Constructor parameters

authforge::AuthForgeClient client(
    "app_id",                       // Required; from dashboard
    "app_secret",                   // Required for online Login/ValidateLicense; pass "" for LoginFromFile only
    "public_key",                   // Required; Ed25519 public key (base64)
    authforge::OnlineHeartbeat::Off,// Optional; ::On enables periodic online check-ins (/auth/heartbeat)
    900,                            // Optional; background timer cadence (check-ins when online, local session checks otherwise)
    "https://auth.authforge.cc",    // Optional; API base URL
    on_failure_callback,            // Optional; void(const std::string& reason, const std::exception* ex)
    15,                             // Optional; HTTP timeout in seconds
    0,                              // Optional; ttlSeconds: grace period (session TTL). 0 = server default (24h). Clamped to [3600, 604800].
    ""                              // Optional; hwidOverride: custom identity (for example "tg:123456789")
);

`ttlSeconds` (grace period)

Requested session token lifetime in seconds for /auth/validate, passed as the 9th constructor parameter. This is the grace period: how long the app keeps running on the signed session without contacting AuthForge. Pass 0 (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() 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.

bool success = client.Login(license_key);

Returns true on success, false otherwise. On success, a background thread re-verifies the signed session locally during the grace period (and sends online check-ins if OnlineHeartbeat::On was passed).

Validate license (no session)

authforge::ValidateLicenseResult r = client.ValidateLicense(license_key);
if (r.valid) {
  // r.sessionToken, r.expiresIn, r.sessionDataJson, r.appVariablesJson, r.licenseVariablesJson
} else {
  // r.errorCode; e.g. invalid_key, nonce_mismatch
}

Same /auth/validate request and Ed25519 verification as Login, without persisting session fields on the client or starting the background thread. Does not invoke the failure callback or std::exit on error; inspect valid / errorCode instead.

Failure callback

If no callback is set (or the callback throws), the SDK calls std::exit(1).

#include "authforge_sdk.h"
#include <iostream>

void on_failure(const std::string& reason, const std::exception* ex) {
    if (reason == "login_failed") {
        std::cerr << "Login failed." << std::endl;
    } else if (reason == "heartbeat_failed") {
        std::cerr << "Session check failed; saving state." << std::endl;
        save_application_state();
    }
    if (ex) {
        std::cerr << "  Detail: " << ex->what() << std::endl;
    }
}

int main() {
    authforge::AuthForgeClient client(
        "YOUR_APP_ID",
        "YOUR_APP_SECRET",
        "YOUR_PUBLIC_KEY",
        authforge::OnlineHeartbeat::Off,
        900,
        "https://auth.authforge.cc",
        on_failure
    );

    // ...
}

If you don’t set an onFailure callback, the SDK terminates the process immediately via std::exit(1). Always set a callback in production.

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 by passing authforge::OnlineHeartbeat::On as the 4th constructor argument:

// Default: activate online, then run through the grace period (24h by default)
authforge::AuthForgeClient client("...", "...", "...");

// Strict policy: periodic online check-ins for fast revocation
authforge::AuthForgeClient strict_client("...", "...", "...", authforge::OnlineHeartbeat::On);

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. Pass an empty appSecret so the air-gapped binary does not contain the App Secret.

authforge::AuthForgeClient client("APP_ID", "", "PUBLIC_KEY");

// Step 1 (customer machine): write an activation request the operator drops into the mint dialog.
std::string request = client.CreateActivationRequest();

// Step 2 (customer machine, after you deliver the file): path or armored text.
if (client.LoginFromFile("license.authforge")) {
  const auto info = client.GetOfflineLicense();
  std::cout << "Offline license valid until " << (info->expiresAt ? *info->expiresAt : "forever") << "\n";
}

Failures call onFailure("offline_login_failed", &exc) with exc.what() set to the code and return false (never std::exit). Codes, in check order: bad_armor, bad_signature, unsupported_version, malformed_payload, wrong_app, expired, hwid_mismatch. client.VerifyLicenseFile(pathOrText) and the free function authforge::VerifyLicenseFile(text, appId, publicKeys, hwid) run the same checks without touching state and return a VerifyLicenseFileResult. 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 `"SERVER"` / `"LOCAL"`

The legacy constructors taking a "SERVER" or "LOCAL" string as the 4th argument are deprecated but still work:

"LOCAL": drop the argument; the grace period is now the default.
"SERVER": pass authforge::OnlineHeartbeat::On instead.

Full example (game)

#include "authforge_sdk.h"
#include <iostream>
#include <string>
#include <atomic>

std::atomic<bool> g_licensed{false};

void on_auth_failure(const std::string& reason, const std::exception* ex) {
    std::cerr << "[AuthForge] " << reason;
    if (ex) std::cerr << ": " << ex->what();
    std::cerr << std::endl;

    g_licensed.store(false);
    // Don't exit here; let the game loop handle shutdown gracefully
}

int main() {
    authforge::AuthForgeClient client(
        "YOUR_APP_ID",
        "YOUR_APP_SECRET",
        "YOUR_PUBLIC_KEY",
        authforge::OnlineHeartbeat::On,  // Strict policy: check in every 15 minutes
        900,
        "https://auth.authforge.cc",
        on_auth_failure
    );

    std::string key;
    std::cout << "Enter license key: ";
    std::getline(std::cin, key);

    if (!client.Login(key)) {
        std::cerr << "Invalid license key." << std::endl;
        return 1;
    }

    g_licensed.store(true);
    std::cout << "Licensed. Starting game..." << std::endl;

    // Game loop
    while (g_licensed.load()) {
        // Update game state
        // Render frame
        // If g_licensed becomes false, show "license expired" dialog
    }

    std::cout << "License expired. Shutting down." << std::endl;
    return 0;
}

Platform notes

Platform	HWID sources	Notes
Windows	`GetAdaptersAddresses`, WMI, `GetVolumeInformation`	Works out of the box with Windows SDK
Linux	`/sys/class/net/*/address`, `/proc/cpuinfo`, `lsblk`	Standard filesystem access
macOS	`getifaddrs`, `sysctl`, `diskutil`	May require Full Disk Access for disk serial

GitHub

Full source, changelog, and issues: AuthForgeCC/authforge-cpp

​Requirements

​Installation

​Option A: FetchContent (CMake)

​Option B: Install prefix + find_package

​Dependencies

​Quick start

​Constructor parameters

​ttlSeconds (grace period)

​Billing

​Login

​Validate license (no session)

​Failure callback

​Grace period and online check-ins

​Offline license files (.authforge)

​Migrating from "SERVER" / "LOCAL"

​Full example (game)

​Platform notes

​GitHub

Requirements

Installation

Option A: `FetchContent` (CMake)

Option B: Install prefix + `find_package`

Dependencies

Quick start

Constructor parameters

`ttlSeconds` (grace period)

Billing

Login

Validate license (no session)

Failure callback

Grace period and online check-ins

Offline license files (`.authforge`)

Migrating from `"SERVER"` / `"LOCAL"`

Full example (game)

Platform notes

GitHub