Skip to main content
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

During license validation (/auth/validate), the server checks the requesting HWID and IP address against your app’s access control lists before validating the license itself.

​
Evaluation order

  1. IP blacklist — If the IP is blacklisted, reject immediately.
  2. IP whitelist — If a whitelist is configured and the IP is NOT on it, reject.
  3. HWID blacklist — If the HWID is blacklisted, reject.
  4. HWID whitelist — If a whitelist is configured and the HWID is NOT on it, reject.
Blacklist takes precedence over whitelist. If an entry appears on both lists, it is blocked.

​
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
# Add an HWID to the blacklist
curl -X POST https://api.authforge.cc/v1/apps/YOUR_APP_ID/security/blacklist \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "hwid", "value": "a1b2c3d4e5f6..." }'

​
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 ranges

​
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: 
curl https://api.authforge.cc/v1/apps/YOUR_APP_ID/security \
  -H "Authorization: Bearer af_live_your_key"

{
  "hwidBlacklist": ["a1b2c3d4..."],
  "hwidWhitelist": [],
  "ipBlacklist": ["203.0.113.50"],
  "ipWhitelist": []
}
Replace entire security config: 
curl -X PUT https://api.authforge.cc/v1/apps/YOUR_APP_ID/security \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hwidBlacklist": ["a1b2c3d4..."],
    "ipBlacklist": ["203.0.113.50", "198.51.100.0"]
  }'
You can include only the lists you want to update — omitted lists remain unchanged. Add/remove individual entries: 
# Add to blacklist
curl -X POST https://api.authforge.cc/v1/apps/YOUR_APP_ID/security/blacklist \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "hwid", "value": "a1b2c3d4..." }'

# Remove from blacklist
curl -X DELETE https://api.authforge.cc/v1/apps/YOUR_APP_ID/security/blacklist \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "hwid", "value": "a1b2c3d4..." }'

# Add to whitelist
curl -X POST https://api.authforge.cc/v1/apps/YOUR_APP_ID/security/whitelist \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "ip", "value": "203.0.113.50" }'

​
Limits

LimitValue
Max entries per list1,000
HWID value max length128 characters
IP value max length45 characters (supports IPv6)

​
Error response

When a request is blocked by a blacklist or whitelist, the SDK receives: 
{
  "status": "failed",
  "error": "blocked"
}
The SDK treats this as a login failure. See SDK Best Practices for guidance on user-facing error messages.

​
Next steps