Skip to main content

​
Frequently Asked Questions

​
Licensing

​
What happens when my credits run out?

Auth calls return no_credits. Apps with online check-ins enabled fail on the next check-in. Apps running through the grace period (the default) continue until the signed session expires (24 hours by default, or whatever TTL the SDK requested; up to 7 days). Set up auto-refill to prevent this.

​
Can a customer use one key on multiple devices?

Yes. Configure maxHwidSlots (1-16) when generating the license. Each new device uses one slot.

​
How do I let a customer move to a new computer?

Reset their HWID bindings from the dashboard (app -> license -> Reset HWID) or via the Developer API.

​
What license key format does AuthForge use?

XXXX-XXXX-XXXX-XXXX using A-Z (excluding I and O) and digits 2-9.

​
Does AuthForge support offline or air-gapped machines?

Yes, in two different ways, and it matters which one you mean.
  • The grace period (default) lets an app keep running for up to 7 days after an online activation. It is session continuation, not offline licensing: the machine must reach AuthForge at least once, and again when the session lapses.
  • Offline license files (.authforge) are for machines that never connect. You mint a signed file in the dashboard or Developer API (1 credit), deliver it out-of-band, and the SDK verifies it locally with your public key and the machine HWID via loginFromFile. No network, ever. Collect the HWID as an activation request (.authforge-request) rather than a pasted string.
Issued files cannot be revoked remotely; they stay valid until their own expiry. Mint short-lived, HWID-bound files and re-issue on a schedule. See Offline license files and Offline licensing best practices.

​
I revoked a license but the offline machine still works

Expected. Revoking online blocks new mints and online activations, but a .authforge file already on a machine is a standalone signed document with no server to ask. It runs until its expiresAt. The license page’s mint history shows every outstanding file and when it lapses; stop re-issuing and the entitlement ends on schedule.

​
SDK & Integration

​
My users are getting hwid_mismatch errors

For online login(), their HWID slots are full. Either increase maxHwidSlots on the license or reset their HWID bindings. HWIDs can change after OS reinstalls, hardware upgrades, or VM migrations. If this is an offline .authforge file, the bound string was probably truncated or wrapped in email. Ask for an activation request from the same SDK that will call loginFromFile; do not re-mint to the old pasted value. See Finding a machine’s HWID.

​
Heartbeats are using too many credits

Heartbeats only happen if you enabled online check-ins, and they’re cheap: 10 successful heartbeats cost 1 credit (billed on every 10th call). At the default 15-minute interval, an always-on app costs about 10 credits/day. If that’s still more than you want, increase the check-in interval (the credit cost scales directly with the number of heartbeats sent), or disable online check-ins entirely and rely on the grace period: the SDK re-verifies the signed session locally, with zero heartbeat credits, until it expires (24h by default). With online check-ins, revocations apply on the next check-in, regardless of interval. Without them, revocations apply when the session expires.

​
The SDK can’t reach the API

Check that auth.authforge.cc is reachable. The SDK uses HTTPS on port 443. Some corporate firewalls and China’s GFW may block it. The SDK respects the apiBaseUrl constructor param if you need to proxy.

​
I’m getting rate_limited errors

/auth/validate is rate-limited to 5 requests per license per minute and 30 per IP per minute. /auth/heartbeat is rate-limited to 6 requests per license per minute (not IP rate-limited). This usually means something is calling login() in a loop instead of once at startup.

​
Billing

​
Do failed auth attempts use credits?

No. Only successful validations (1 credit), successful heartbeats (1 credit per 10) and successful offline file mints (1 credit each) consume credits. Verifying an offline file on the end machine is free.

​
What payment methods do you accept?

Credit and debit cards via Stripe. No PayPal or crypto at this time.

​
Can I get a refund on credits?

Contact support. Unused credits don’t expire.

​
Security

​
Is my App Secret safe in the binary?

The App Secret authenticates /auth/validate requests, not webhook delivery and not Developer API access. Extracting it doesn’t let an attacker create or revoke licenses. However, obfuscating your binary is still recommended.

​
Can someone replay a captured auth request?

/auth/validate requests include a unique nonce and the server rejects duplicate nonces. Validate and heartbeat success responses are Ed25519-signed by AuthForge with your app’s private signing key. SDKs verify every signed payload using your app’s public key. /auth/validate additionally enforces per-request nonce matching; heartbeats rely on the short-lived session token + signature chain for replay protection.