Offline license files (.authforge)

​

Offline file vs grace period

​

Revocation: read this before you mint

• Prefer short expiries (30 to 90 days) and re-issue on a schedule. Treat re-issuing as your revocation lever.
• Prefer HWID-bound files. An unbound (any) file works on every machine that has a copy.
• Mint lifetime files only for perpetual licenses where you accept that the entitlement is permanent.
• Keep mint history (the dashboard shows it per license) so you know exactly which files exist and when they lapse.

​

Minting a file

​

Dashboard

1. Open the license (Applications -> app -> Licenses -> license page) and click Mint .authforge file.
2. Pick an expiry. Presets are 30 days, 90 days, 1 year, the license expiry, or Lifetime (perpetual licenses only). The file can never outlive the license.
3. Pick a machine binding. Bound to specific HWIDs (recommended) prefills the HWIDs already bound to the license. Prefer an activation request (.authforge-request) over a pasted HWID: the dashboard checksums the file so email damage becomes a clear error instead of a silent hwid_mismatch. You can still paste the getter (getHwid() / get_hwid() / HWID() / hwid() / GetHwid()). Any machine requires an explicit acknowledgement.
   Collect the HWID from the same SDK (and language) that will call loginFromFile. HWID fingerprints are not portable across SDKs: a machine reports a different value from the Node SDK than from the C# SDK. A file bound to the wrong one fails with hwid_mismatch. If your product uses several SDKs on the same box, pass hwidOverride with an identifier you control instead.
4. Click Mint & download. The browser downloads <licenseKey>.authforge and 1 credit is charged. The file body is never stored server-side, only its SHA-256, so download it now.

​

Developer API

curl -X POST https://api.authforge.cc/v1/licenses/XXXX-XXXX-XXXX-XXXX/offline-files \
  -H "Authorization: Bearer af_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expiresAt": "2027-01-01T00:00:00Z",
    "hwidMode": "bound",
    "hwids": ["3f1c...e9a2"]
  }'

​

Mint rules

• License must be active and not expired; the app must not be paused.
• expiresAt must be in the future and on or before the license expiry. null (lifetime) is only accepted for licenses without an expiry.
• hwidMode: "bound" needs 1 to 16 HWIDs. hwidMode: "any" needs allowUnbound: true.
• Rate limited: 30 mints per minute per account, 10 per minute per license.
• Billing: 1 credit per successful mint, debited through the same path as /auth/validate (so your app’s hourly/daily burn caps apply). Rejected mints are free. A mint fails with no_credits before anything is signed.
• Every mint is audited (actor, time, license, expiry, HWID policy, file id and hash).

​

Verifying on the air-gapped machine

• verifyLicenseFile(...): a pure function that checks a file and returns the decoded license or an error code. No client state, no network.
• client.loginFromFile(pathOrText): verifies with the client’s configured app id, public key(s) and HWID, then marks the client authenticated so isAuthenticated(), getLicenseVariables() and getAppVariables() work exactly as after an online login(). It never starts the grace-period timer or online check-ins. logout() clears it.

from authforge import AuthForgeClient

client = AuthForgeClient(app_id="APP_ID", app_secret=None, public_key="PUBLIC_KEY",
                         on_failure=lambda reason, exc: print(reason, exc))

print("HWID:", client.get_hwid())  # customer sends this to you before you mint

if client.login_from_file("license.authforge"):
    info = client.get_offline_license()
    print("valid until", info["expires_at"] or "forever", client.get_license_variables())

import { AuthForgeClient } from "@authforgecc/sdk";

const client = new AuthForgeClient({ appId: "APP_ID", publicKey: "PUBLIC_KEY",
  onFailure: (reason, error) => console.error(reason, error?.message) });

console.log("HWID:", client.getHwid());

if (client.loginFromFile("./license.authforge")) {
  console.log("valid until", client.getOfflineLicense().expiresAt ?? "forever", client.getLicenseVariables());
}

client, _ := authforge.New(authforge.Config{AppID: "APP_ID", PublicKey: "PUBLIC_KEY"})
fmt.Println("HWID:", client.HWID())

lic, err := client.LoginFromFile("license.authforge")
if errors.Is(err, authforge.ErrOfflineExpired) {
	log.Fatal("offline license expired - request a new file")
} else if err != nil {
	log.Fatal(err)
}
fmt.Println("valid until", lic.ExpiresAt) // nil = lifetime

let client = AuthForgeClient::new(AuthForgeConfig {
    app_id: "APP_ID".into(), public_key: "PUBLIC_KEY".into(),
    ..Default::default()
});
println!("HWID: {}", client.hwid());

match client.login_from_file("license.authforge") {
    Ok(lic) => println!("valid until {:?}", lic.expires_at), // None = lifetime
    Err(OfflineLicenseError::HwidMismatch) => eprintln!("this file is bound to another machine"),
    Err(err) => eprintln!("rejected: {err}"),
}

var client = new AuthForgeClient(appId: "APP_ID", appSecret: "", publicKey: "PUBLIC_KEY",
    onFailure: (reason, ex) => Console.Error.WriteLine($"{reason}: {ex?.Message}"));
Console.WriteLine($"HWID: {client.GetHwid()}");

if (client.LoginFromFile("license.authforge"))
{
    Console.WriteLine($"valid until {client.GetOfflineLicense()!.ExpiresAt ?? "forever"}");
}

authforge::AuthForgeClient client("APP_ID", "", "PUBLIC_KEY");
std::cout << "HWID: " << client.GetHwid() << "\n";

if (client.LoginFromFile("license.authforge")) {
  const auto info = client.GetOfflineLicense();
  std::cout << "valid until " << (info->expiresAt ? *info->expiresAt : "forever") << "\n";
}

​

Rejection codes

​

File format (version 1)

-----BEGIN AUTHFORGE LICENSE-----
Version: 1
App-Id: 3d3a...
License: XXXX-XXXX-XXXX-XXXX
Key-Id: 8c9e...
Expires-At: 2027-01-01T00:00:00.000Z

eyJ2IjoxLCJ0eXAiOiJhdXRoZm9yZ2UtbGljZW5zZSIsImFwcElkIjoiM2QzYS4u
...
-----END AUTHFORGE LICENSE-----
-----BEGIN AUTHFORGE SIGNATURE-----
OUi4frE6lPUXqvZDs4nHvbHGsR4ZKBis6lrJjnZfPbFinPtbVBrE/pwW9F6PHJsx
G+RbBBOIN+JN70CcDsOrAg==
-----END AUTHFORGE SIGNATURE-----

• Headers are informational. SDKs read every decision-relevant field from the signed payload, never from the headers.
• Payload (base64 JSON): v (1), typ (authforge-license), appId, licenseKey, jti (unique file id), kid (the app signing key id), issuedAt, expiresAt (ISO 8601 or null), hwid ({ "mode": "bound", "hwids": [...] } or { "mode": "any" }), and optional snapshots taken at mint time: label, licenseExpiresAt, licenseVariables, appVariables.
• Signed bytes: the Ed25519 signature covers the UTF-8 bytes of the base64 payload string (body lines joined, all whitespace removed). This is the same contract as /auth/validate responses, which is why every SDK reuses its existing verify routine and why there is no JSON canonicalisation step.
• Keys: the file is signed with your app’s existing per-app Ed25519 key (KMS-protected in AuthForge) and verified with the same public key you already embed in your app. Rotating the app key means new files carry the new kid; SDKs accept a list of public keys, so keep the old one in the list until every old file has expired.
• Versioning: SDKs reject any v other than 1 with unsupported_version. Future versions will be additive and announced with an SDK release.

​

Where this fits

• Default: online login() + grace period. Cheapest, revocable at the next activation, zero operator work.
• High-value software with connectivity: online login() + online check-ins for fast revocation.
• Machines that can never connect: offline license files, short-lived and HWID-bound, re-issued on a schedule. See Offline licensing best practices.