Documentation Index
Fetch the complete documentation index at: https://docs.authforge.cc/llms.txt
Use this file to discover all available pages before exploring further.
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:
| Field | Description |
|---|
licenseKey | The key string itself |
appId | The app this license belongs to |
status | active or revoked |
expiresAt | ISO 8601 expiration date, or null for lifetime licenses |
maxHwidSlots | How many devices can use this key simultaneously (1–16) |
hwidList | Array of bound hardware IDs |
label | Optional label for your records (e.g., order ID) |
createdAt | When the license was created |
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.
| Operation | Cost |
|---|
| Successful license validation | 1 credit |
| 10 successful heartbeats | 1 credit |
| Tier | Credits | Price |
|---|
| 10k | 10,000 | $10 |
| 30k | 30,000 | $15 |
| 100k | 100,000 | $30 |
| 500k | 500,000 | $100 |
| 1M | 1,000,000 | $150 |
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.
On each interval, the SDK re-verifies the stored session signature locally without making a network call. When the session token expires (default 24 hours, configurable per-SDK up to 7 days), the SDK triggers the failure handler. In SERVER mode, each successful heartbeat mints a fresh session token, so long-running apps never expire.Pros: Works offline after initial login. Zero heartbeat credit consumption.Cons: Revocations don’t take effect until the next server-side check. If the app stays offline longer than the session TTL (~24h by default) without a successful heartbeat, the local session expires and the SDK triggers the failure handler.Use when: Your users may be offline, you want to minimize credit usage, or instant revocation isn’t critical.
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.
| Property | Value |
|---|
| Default lifetime | 24 hours |
| Minimum lifetime | 1 hour (3600s) |
| Maximum lifetime | 7 days (604800s) |
| Refresh | Every successful heartbeat mints a fresh token, preserving the originally requested TTL |
| Revocation | Revoking a license invalidates all of its tokens on the next heartbeat |
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:
| Field | Meaning |
|---|
expiresIn | Unix seconds when the session token expires (historical field; same instant as sessionExpiresAt) |
sessionExpiresAt | ISO 8601 session expiry (for display and clarity) |
licenseExpiresAt | ISO 8601 license expiry, or null for lifetime keys |
maxHwidSlots | Seat limit for this license |
hwidCount | Number of HWIDs currently bound |
licenseLabel | Optional dashboard label (only present when set) |
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:
| Event | Trigger |
|---|
license.validated | Successful authentication via SDK |
license.created | License key generated |
license.revoked | License revoked |
license.activated | Revoked license re-activated |
license.hwid_bound | HWID bound to a license slot |
license.hwid_reset | HWID bindings cleared |
license.deleted | License permanently deleted |
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.
