Skip to main content
Control which devices and IP addresses can authenticate with your application.

​
Get security config

​
GET
Retrieve the current blacklist and whitelist configuration for an application.

​
Path parameters

ParamTypeDescription
appIdstringThe application ID

​
Example

curl https://api.authforge.cc/v1/apps/YOUR_APP_ID/security \
  -H "Authorization: Bearer af_live_your_key"

​
Response (200)

{
  "hwidBlacklist": ["a1b2c3d4e5f6..."],
  "hwidWhitelist": [],
  "ipBlacklist": ["203.0.113.50"],
  "ipWhitelist": []
}
Empty arrays indicate no entries for that list. An empty whitelist means whitelist mode is not active (all values are allowed).

​
Update security config

​
PUT
Replace the security configuration. Only included fields are updated — omitted lists remain unchanged.

​
Request body

FieldTypeRequiredDescription
hwidBlackliststring[]NoHWIDs to block (max 1,000)
hwidWhiteliststring[]NoAllowed HWIDs only (max 1,000)
ipBlackliststring[]NoIPs to block (max 1,000)
ipWhiteliststring[]NoAllowed IPs only (max 1,000)

​
Example

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": ["a1b2c3d4e5f6...", "7g8h9i0j1k2l..."],
    "ipBlacklist": ["203.0.113.50"]
  }'

​
Response (200)

{
  "hwidBlacklist": ["a1b2c3d4e5f6...", "7g8h9i0j1k2l..."],
  "hwidWhitelist": [],
  "ipBlacklist": ["203.0.113.50"],
  "ipWhitelist": []
}

​
Errors

HTTPCodeCause
400bad_requestInvalid entry format, exceeds 1,000 entries per list
403forbiddenThe app doesn’t belong to your account

​
Clearing a list

Set the list to an empty array: 
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": []}'

​
Add to blacklist

​
POST
Add a single HWID or IP to the blacklist.

​
Request body

FieldTypeRequiredDescription
typestringYes"hwid" or "ip"
valuestringYesThe HWID hash or IP address to block

​
Example

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..."}'

​
Response (200)

{ "ok": true }

​
Remove from blacklist

​
DELETE
Remove a single HWID or IP from the blacklist.

​
Request body

FieldTypeRequiredDescription
typestringYes"hwid" or "ip"
valuestringYesThe entry to remove

​
Example

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": "a1b2c3d4e5f6..."}'

​
Response (200)

{ "ok": true }

​
Add to whitelist

​
POST
Add a single HWID or IP to the whitelist. Enabling a whitelist restricts authentication to only listed entries.

​
Request body

FieldTypeRequiredDescription
typestringYes"hwid" or "ip"
valuestringYesThe HWID hash or IP address to allow

​
Example

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": "198.51.100.10"}'

​
Response (200)

{ "ok": true }
Adding an entry to a whitelist activates allowlist mode for that type. All non-listed HWIDs or IPs will be blocked.

​
Remove from whitelist

​
DELETE
Remove a single HWID or IP from the whitelist. If the whitelist becomes empty, allowlist mode is deactivated.

​
Request body

FieldTypeRequiredDescription
typestringYes"hwid" or "ip"
valuestringYesThe entry to remove

​
Example

curl -X DELETE 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": "198.51.100.10"}'

​
Response (200)

{ "ok": true }

​
Limits

ConstraintValue
Max entries per list1,000
HWID value max length128 characters
IP value max length45 characters (IPv4 and IPv6)
HWID value min length1 character
IP value min length7 characters

​
Evaluation order

During authentication, lists are checked in this order:
  1. IP blacklist (reject if matched)
  2. IP whitelist (reject if list is non-empty and IP not listed)
  3. HWID blacklist (reject if matched)
  4. HWID whitelist (reject if list is non-empty and HWID not listed)
Blacklist always takes precedence. An entry present on both blacklist and whitelist is blocked.