Security Best Practices

​

Protect your App Secret

# Bad
client = AuthForgeClient(app_secret="550e8400-e29b-41d4-a716-446655440000")

# Good
client = AuthForgeClient(app_secret=os.environ["AUTHFORGE_SECRET"])

​

Authenticate early

# Bad; app runs unprotected for several seconds
initialize_app()
load_plugins()
setup_ui()
# ... much later
client.login(key)

# Good; nothing runs before auth
client = AuthForgeClient(...)
if not client.login(key):
    exit(1)
initialize_app()

​

Minimize error details

# Bad; reveals implementation details
print(f"Signature verification failed: expected {expected}, got {actual}")
print(f"Nonce mismatch: sent {sent_nonce}, received {recv_nonce}")

# Good; generic message
print("Authentication failed. Please try again or contact support.")

​

Enable online check-ins for high-value software

• Freezing or rolling back the system clock
• Patching the SDK to skip the local signature check

​

Don’t trust the client

• Don’t gate features with a simple boolean. Instead of if (licensed) { runProFeature() }, read license variables and check specific capabilities.
• Don’t store the license status in a predictable location. Avoid a single isLicensed = true field that can be patched.
• Spread auth checks. Don’t check the license in a single function; verify state at multiple points in your application.

​

Obfuscation (defense in depth)

​

Network security

• Always use HTTPS. The SDK communicates with https://auth.authforge.cc by default. Never override the base URL to use HTTP.
• Pin the certificate if your platform supports it, to prevent MITM with a trusted CA compromise.
• Validate the nonce on /auth/validate. The SDK does this automatically; the nonce in the response must match the one you sent. Heartbeats don’t use nonce replay detection; they rely on the signed short-lived session token instead.

​

Self-ban safely

• Prefer post-session self-ban for revoke. Revoke by key only when you have a valid sessionToken from a successful login.
• Never revoke by key pre-session. Before activation, a licenseKey value can be attacker-controlled. Revoking at that stage can ban random or other customers’ keys.
• Use pre-session for containment only. Pre-session self-ban should be limited to blacklistHwid and/or blacklistIp.
• Keep nonce hygiene. Pre-session self-ban uses nonce replay protection; always send a fresh nonce.
• Treat self-ban as high risk action. Add local anti-tamper confidence thresholds so noisy detections do not mass-ban legitimate users.

​

Rate limiting

• Per IP address: up to 30 /auth/validate requests per minute.
• Per license key: up to 5 /auth/validate requests per minute (in addition to the per-IP limit). Unlimited-seat (shared) keys get this allowance per device instead, with a ceiling of 300 per minute across all devices on the key.

​

HWID and IP security

• Blacklist known-bad HWIDs: If you discover a cracked copy, blacklist the HWID to prevent re-authentication.
• Use IP whitelists for enterprise: Restrict authentication to known office IP ranges.
• Monitor for anomalies: If a license key is being validated from many different HWIDs (more than the slot count allows, via resets), investigate abuse.

​

API key security

• Don’t expose API keys in client-side code. API calls should only be made from your server.
• Use separate keys for different environments (development, staging, production).
• Audit key usage: If a key is compromised, delete it and create a new one. Keys are scoped to your account, so a compromised key gives access to all your apps’ license management.

​

Webhook security

• Always verify the signature on incoming webhook requests using the X-AuthForge-Signature-V2 header, and reject requests whose t is more than 5 minutes old. The legacy X-AuthForge-Signature header doesn’t cover the timestamp, so it can’t stop replays.
• Use HTTPS for your webhook endpoint.
• Don’t expose your webhook secret in client code or logs.
• Validate the event type: only process events you expect.

​

Incident response

1. Identify the HWID from your auth logs (if available via webhooks or the dashboard).
2. Blacklist the HWID to block future authentication from that machine.
3. Rotate your App Secret if you suspect it was extracted from the binary.
4. Update your binary with stronger obfuscation and push an update.
5. Review your integration against this checklist.