AuthForge supports per-app access control lists for HWIDs and IP addresses. Use them to block pirated copies, restrict beta access, or geo-limit your application.
How it works
The same access-list check runs on both public auth endpoints:
/auth/validate (login): the requesting HWID and source IP are checked before the license itself is looked up, so a blocked device never learns whether the key is valid./auth/heartbeat (online check-ins): every check-in re-checks the HWID and the current source IP against the lists as they are now. A device blacklisted after login, a whitelist tightened mid-session, or a session that moved to a different IP is rejected at its next check-in, not only at the next login.
List changes therefore take effect at the next online check-in for apps with check-ins enabled, and at session expiry (up to the configured TTL) otherwise, when the SDK has to call /auth/validate again.
Evaluation order
- IP blacklist: If the IP is blacklisted, reject immediately.
- IP whitelist: If the IP whitelist has any entries and the IP is NOT on it, reject.
- HWID blacklist: If the HWID is blacklisted, reject.
- HWID whitelist: If the HWID whitelist has any entries and the HWID is NOT on it, reject.
IP lists are evaluated before HWID lists; the first failing step decides the result.
Blacklist takes precedence over whitelist. Within each type the blacklist is checked first, so an entry that appears on both lists is blocked. Whitelisting a value never overrides a blacklist entry.
An empty whitelist means allowlist mode is off. With no entries, every value of that type is allowed (subject to the blacklist). Adding the first entry turns allowlist mode on for that type; removing the last entry turns it off again. The IP and HWID whitelists are independent: you can restrict IPs without restricting HWIDs, and vice versa.
Matching is exact. Values are compared as exact strings: no CIDR ranges, wildcards, or case folding. The HWID must match the exact string your SDK sends, and the IP must match the exact address AuthForge sees as the source.
When a request is rejected, the auth log records blocked with one of these detail values so you can see which list matched: ip blacklisted, ip not whitelisted, hwid blacklisted, hwid not whitelisted.
HWID blacklist
Block specific hardware IDs from authenticating. The HWID is the SHA-256 hash the SDK collects from the user’s machine.
Use cases:
- Block a known pirated/cracked machine fingerprint
- Revoke access from a specific device without revoking the entire license
HWID whitelist
When set, only listed HWIDs can authenticate. This is allowlist mode; any HWID not on the list is rejected.
Use cases:
- Restrict a beta to specific testers’ machines
- Lock down access to known-good devices in an enterprise deployment
Enabling a HWID whitelist blocks ALL devices not explicitly listed. Make sure you’ve added all expected HWIDs before enabling.
IP blacklist
Block specific IP addresses from authenticating.
Use cases:
- Block IPs associated with abuse
- Block known VPN/proxy exit IPs (each address is listed individually; ranges are not supported)
IP whitelist
When set, only listed IPs can authenticate. Useful for enterprise environments where users connect from known office IPs.
Configuration
Via the dashboard
Go to your app’s Settings → Security. You’ll see four sections for each list type. Add entries and click Save.
Via the Developer API
Get current security config:
Replace entire security config:
You can include only the lists you want to update; omitted lists remain unchanged.
Add/remove individual entries:
Limits
Error response
When a request is blocked by a blacklist or whitelist, the SDK receives:
On /auth/validate the SDK treats this as a login failure. On a check-in it is a definitive failure: the SDK clears the stored session, stops background checks, and calls your failure callback. See SDK Best Practices for guidance on user-facing error messages.
Next steps
