C# SDK - AuthForge

Requirements

.NET 6.0 or later
BouncyCastle.Cryptography (pulled in transitively with the AuthForge package)

Installation

Add the AuthForge package from NuGet:

dotnet add package AuthForge

Prefer a source-only layout? Copy AuthForgeClient.cs from GitHub and reference BouncyCastle.Cryptography explicitly. The NuGet package is recommended for most apps.

Quick start

using AuthForge;

var client = new AuthForgeClient(
    appId: "YOUR_APP_ID",
    appSecret: "YOUR_APP_SECRET",
    publicKey: "YOUR_PUBLIC_KEY"
);

Console.Write("Enter license key: ");
var key = Console.ReadLine() ?? "";

if (client.Login(key))
{
    Console.WriteLine("Authenticated!");
    // Your app logic here; the signed session covers the grace period
}
else
{
    Console.WriteLine("Invalid license key.");
    Environment.Exit(1);
}

Constructor parameters

var client = new AuthForgeClient(
    appId: "...",                   // Required; from dashboard
    appSecret: "...",               // Required for online Login/ValidateLicense; pass "" 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: 900,         // Optional; background timer cadence (check-ins when online, local session checks otherwise)
    apiBaseUrl: "https://auth.authforge.cc",  // Optional
    onFailure: null,                // Optional; Action<string, Exception?>
    requestTimeout: 15,             // Optional; HTTP timeout in seconds
    ttlSeconds: null,               // Optional; grace period (session TTL). null = server default (24h). Clamped to [3600, 604800].
    hwidOverride: null              // Optional; custom identity (for example "tg:123456789")
);

`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() 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(licenseKey);

Returns 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)

var result = client.ValidateLicense(licenseKey);
if (result.Valid) {
    Console.WriteLine(result.SessionToken);
} else {
    Console.WriteLine(result.ErrorCode);
}

Same /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 your OnFailure callback. If no callback is set (or the callback throws), the SDK calls Environment.Exit(1).

void HandleFailure(string reason, Exception? exception)
{
    if (reason == "login_failed")
    {
        Console.WriteLine("Login failed; check your license key.");
    }
    else if (reason == "heartbeat_failed")
    {
        Console.WriteLine("Session check failed; saving state.");
        SaveApplicationState();
    }
}

var client = new AuthForgeClient(
    appId: "YOUR_APP_ID",
    appSecret: "YOUR_APP_SECRET",
    publicKey: "YOUR_PUBLIC_KEY",
    onFailure: HandleFailure
);

If you don’t set onFailure, the SDK terminates the process immediately on any failure. Always set a callback in production to handle graceful shutdown.

Reading variables

After a successful login, app variables and license variables are available:

if (client.Login(licenseKey))
{
    // App-wide variables
    var appVars = client.AppVariables;
    if (appVars.TryGetValue("maintenanceMode", out var maintenance) && maintenance is true)
    {
        Console.WriteLine("Server is under maintenance.");
        Environment.Exit(0);
    }

    // Per-license variables
    var plan = client.LicenseVariables.GetValueOrDefault("plan", "basic");
    if (plan?.ToString() == "pro")
    {
        EnableProFeatures();
    }
}

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)
var client = new AuthForgeClient(
    appId: "...",
    appSecret: "...",
    publicKey: "YOUR_PUBLIC_KEY",
    ttlSeconds: 259200  // Optional: extend the grace period to 3 days (clamped to 1h-7d)
);

// Strict policy: periodic online check-ins for fast revocation
var strictClient = new AuthForgeClient(
    appId: "...",
    appSecret: "...",
    publicKey: "YOUR_PUBLIC_KEY",
    onlineHeartbeat: true,
    heartbeatInterval: 900  // 15 minutes (default)
);

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

var client = new AuthForgeClient(appId: "APP_ID", appSecret: "", publicKey: "PUBLIC_KEY");

// Step 1 (customer machine): write an activation request the operator drops into the mint dialog.
File.WriteAllText("machine.authforge-request", client.CreateActivationRequest());

// Step 2 (customer machine, after you deliver the file): path or armored text.
if (client.LoginFromFile("license.authforge"))
{
    var info = client.GetOfflineLicense()!;
    Console.WriteLine($"Offline license valid until {info.ExpiresAt ?? "forever"}");
}

Failures call 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": use onlineHeartbeat: true instead.

Full example (WPF)

using System.Windows;
using AuthForge;

public partial class App : Application
{
    private AuthForgeClient? _authClient;

    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);

        _authClient = new AuthForgeClient(
            appId: "YOUR_APP_ID",
            appSecret: "YOUR_APP_SECRET",
            publicKey: "YOUR_PUBLIC_KEY",
            onlineHeartbeat: true, // Optional strict policy: check in every 15 minutes
            onFailure: OnAuthFailure
        );

        var dialog = new LicenseDialog();
        if (dialog.ShowDialog() != true)
        {
            Shutdown();
            return;
        }

        if (!_authClient.Login(dialog.LicenseKey))
        {
            MessageBox.Show("Invalid license key.", "Authentication Failed",
                MessageBoxButton.OK, MessageBoxImage.Error);
            Shutdown();
            return;
        }

        var mainWindow = new MainWindow();
        mainWindow.Show();
    }

    private void OnAuthFailure(string reason, Exception? ex)
    {
        Dispatcher.Invoke(() =>
        {
            // Save user's work before shutting down
            (MainWindow as MainWindow)?.SaveState();

            MessageBox.Show(
                "License verification failed. Your work has been saved.",
                "Authentication Error",
                MessageBoxButton.OK,
                MessageBoxImage.Warning
            );

            Shutdown();
        });
    }
}

GitHub

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

​Requirements

​Installation

​Quick start

​Constructor parameters

​ttlSeconds (grace period)

​Billing

​Login

​Validate license (no session)

​Failure callback

​Reading variables

​Grace period and online check-ins

​Offline license files (.authforge)

​Migrating from heartbeatMode

​Full example (WPF)

​GitHub

Requirements

Installation

Quick start

Constructor parameters

`ttlSeconds` (grace period)

Billing

Login

Validate license (no session)

Failure callback

Reading variables

Grace period and online check-ins

Offline license files (`.authforge`)

Migrating from `heartbeatMode`

Full example (WPF)

GitHub