Skip to main content

​
Apps

An app represents the software you’re protecting. Each app has:
  • App ID: A UUID that identifies your app. Public (embedded in your binary).
  • App Secret: A UUID used to authenticate /auth/validate requests. Keep this secret. Rotatable via the dashboard.
  • Public Key: A base64 Ed25519 public key used by SDKs to verify signed /auth/validate and /auth/heartbeat success responses.
  • Settings: Configuration for your app (variables, security rules, webhooks).
You can create multiple apps under one account. Each app has its own license keys, variables, and security settings.

​
License Keys

License keys are alphanumeric strings in the format XXXX-XXXX-XXXX-XXXX (using A–Z excluding I and O, digits 2–9). Each key is bound to a single app. A license has the following properties: Generate keys in the dashboard or programmatically via the Developer API.

​
HWID (Hardware ID)

A hardware fingerprint of the user’s machine. Each SDK collects stable system identifiers (such as MAC address, CPU, hostname, or disk serial; varying by language and platform) and computes a SHA-256 hash. The result is a 64-character hex string. The exact inputs differ per SDK to use the most reliable identifiers available in each language’s standard library. The backend treats the HWID as an opaque string; it only needs to be stable and unique per machine. Important: HWID strings are SDK-specific. The same physical computer can produce different HWIDs when using different AuthForge SDKs (for example, Python vs C#). See Hardware locking (HWID) for how that affects seats, support, and security lists. The HWID is sent during license validation. If the license hasn’t seen this HWID before and has available slots, the server binds it. If all slots are full and the HWID doesn’t match any bound device, authentication fails with hwid_mismatch.

​
HWID Slots

The number of machines a single license key can be active on simultaneously. When a user authenticates from a new device:
  • If there’s an open slot, the HWID is bound automatically.
  • If all slots are full, authentication fails.
To let a customer move to a new machine, reset their HWID bindings from the dashboard or via the API (reset-hwid action).

​
Credits

Credits are the unit of billing in AuthForge. Every billable operation deducts credits from your account. Heartbeat billing is debited on every 10th successful heartbeat. Heartbeat credits are not prepaid; the session itself is short-lived (see Session TTL), so “every 10th heartbeat” is literally how many billable events happened. Purchase credits in the dashboard. Available tiers: Set up auto-refill to automatically purchase credits when your balance drops below a threshold.

​
Heartbeats

After a successful login, the SDK runs periodic background checks to verify the license is still valid. The default interval is 15 minutes. If a heartbeat detects the license has been revoked, expired, or the session is invalid, the SDK triggers your onFailure callback (or terminates the process if no callback is set).

​
Heartbeat Modes

On each interval, the SDK sends POST /auth/heartbeat with the session token. The server verifies the token + signature chain, checks the license status, and returns a new signed response. SDKs verify every heartbeat signature with your app’s Ed25519 public key.Pros: Catches revocations immediately on the next heartbeat. Real-time enforcement. Any heartbeat interval ≥ 1s is economically safe; heartbeats cost 1 credit per 10 calls.Cons: Requires network connectivity.Use when: You need instant revocation enforcement, your users are always online, or you’re protecting high-value software.

​
Session Tokens

A successful /auth/validate response includes a signed session token that the SDK stores and replays on every heartbeat. The token carries the HWID binding, license key, and (if the SDK requested a custom lifetime) a ttl claim. SDKs expose a ttlSeconds / session_ttl_seconds / SessionTTL configuration option so you can tune how long the SDK can keep running without reaching the server (LOCAL mode) before forcing a re-login. The server silently clamps out-of-range values.

​
Signed payload fields

Successful /auth/validate and /auth/heartbeat responses include a signed JSON payload (base64 in the payload field) in addition to the nested session JWT in sessionToken. Besides appVariables / licenseVariables on validate, the payload includes: Heartbeats repeat the entitlement fields when applicable so long-running clients see updates (for example if an admin changes seats or expiry) without calling validate again.

​
Developer API

A server-to-server REST API for automating license management from your own backend. Authenticated with API keys (prefixed af_live_). Use the Developer API to:
  • Create licenses programmatically (e.g., after a Stripe payment)
  • Revoke, activate, extend, or reset HWID on licenses
  • List and query licenses
  • Manage app variables, webhooks, and security settings
See the API Reference for full documentation.

​
App Variables

Key-value pairs set per app, delivered to every SDK client during authentication in the appVariables field of the signed payload. Use cases:
  • Feature flags: "maintenanceMode": true
  • Remote config: "maxUploadSizeMb": 50
  • Messages: "motd": "v2.0 releasing Friday!"
  • Version gating: "minVersion": "1.5.0"
Limits: max 50 keys, 4 KB total, flat values only (string, number, or boolean). Set via the dashboard or the Variables API.

​
License Variables

Key-value pairs set per license, delivered only to that specific license holder during authentication in the licenseVariables field. Use cases:
  • Plan tiers: "plan": "pro"
  • Per-user limits: "maxProjects": 10
  • Custom metadata: "customerName": "Acme Corp"
Same limits as app variables. Set via the dashboard or the Variables API.

​
Webhooks

Real-time HTTP notifications sent to your server when license events occur. Each delivery is HMAC-SHA256 signed with your webhook secret for verification. Supported events: Max 5 webhooks per app. See Webhooks for setup and verification details.

​
Blacklists & Whitelists

Per-app access control lists for HWIDs and IP addresses:
  • HWID blacklist: Block specific hardware IDs from authenticating.
  • HWID whitelist: When set, only listed HWIDs can authenticate (allowlist mode).
  • IP blacklist / whitelist: Same concept for IP addresses.
Blacklist takes precedence over whitelist. Max 1,000 entries per list. See Security for configuration details.