Blacklists & Whitelists

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

IP blacklist: If the IP is blacklisted, reject immediately.
IP whitelist: If a whitelist is configured and the IP is NOT on it, reject.
HWID blacklist: If the HWID is blacklisted, reject.
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

Limit	Value
Max entries per list	1,000
HWID value max length	128 characters
IP value max length	45 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

Security API Reference; Full endpoint documentation
Security Best Practices; Hardening your AuthForge integration

​How it works

​Evaluation order

​HWID blacklist

​HWID whitelist

​IP blacklist

​IP whitelist

​Configuration

​Via the dashboard

​Via the Developer API

​Limits

​Error response

​Next steps

How it works

Evaluation order

HWID blacklist

HWID whitelist

IP blacklist

IP whitelist

Configuration

Via the dashboard

Via the Developer API

Limits

Error response

Next steps