Security API Reference

Control which devices and IP addresses can authenticate with your application.

Response signature model (Ed25519)

AuthForge signs /auth/validate and /auth/heartbeat success responses with a per-app Ed25519 private key.

SDKs verify signature against the exact base64 payload string using your app’s publicKey.
appSecret authenticates validate requests, but is not used for response signature verification.
Response shape includes keyId so clients can identify which signing key version produced the signature.

Success response shape

{
  "status": "success",
  "payload": "<base64-encoded JSON payload>",
  "signature": "<base64 Ed25519 signature>",
  "keyId": "<app signing key version>"
}

This prevents network-level payload forgery without access to your app’s private signing key.

Tamper self-ban endpoint (public auth)

When your app detects tampering (anti-debug, runtime integrity checks, patch detection), you can call:

Trigger a self-ban request against the public auth host (https://auth.authforge.cc).

Request modes

/auth/selfban supports two request styles:

Pre-session: appId, appSecret, licenseKey, hwid, nonce
Post-session: appId, sessionToken, hwid

Common optional flags:

Field	Type	Default	Meaning
`revokeLicense`	boolean	`false` pre-session / `true` post-session	Revoke the license key (post-session only)
`blacklistHwid`	boolean	`true`	Add current HWID to app HWID blacklist
`blacklistIp`	boolean	`true`	Add caller IP to app IP blacklist

Critical safety rule

Pre-session requests cannot revoke by key. If a pre-session request sets revokeLicense: true, the API returns revoke_requires_session.

This prevents accidentally revoking arbitrary or attacker-supplied keys before the key is proven by a valid authenticated session.

Example (pre-session, blacklist only)

curl -X POST https://auth.authforge.cc/auth/selfban \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "YOUR_APP_ID",
    "appSecret": "YOUR_APP_SECRET",
    "licenseKey": "AF-XXXX-XXXX-XXXX",
    "hwid": "device-hwid",
    "nonce": "fresh-random-nonce",
    "revokeLicense": false,
    "blacklistHwid": true,
    "blacklistIp": true
  }'

Example (post-session, full lockout)

curl -X POST https://auth.authforge.cc/auth/selfban \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "YOUR_APP_ID",
    "sessionToken": "SESSION_TOKEN_FROM_VALIDATE",
    "hwid": "device-hwid",
    "revokeLicense": true,
    "blacklistHwid": true,
    "blacklistIp": true
  }'

Get security config

Retrieve the current blacklist and whitelist configuration for an application.

Path parameters

Param	Type	Description
`appId`	string	The 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

Replace the security configuration. Only included fields are updated; omitted lists remain unchanged.

Request body

Field	Type	Required	Description
`hwidBlacklist`	string[]	No	HWIDs to block (max 1,000)
`hwidWhitelist`	string[]	No	Allowed HWIDs only (max 1,000)
`ipBlacklist`	string[]	No	IPs to block (max 1,000)
`ipWhitelist`	string[]	No	Allowed 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

HTTP	Code	Cause
400	`bad_request`	Invalid entry format, exceeds 1,000 entries per list
403	`forbidden`	The 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

Add a single HWID or IP to the blacklist.

Request body

Field	Type	Required	Description
`type`	string	Yes	`"hwid"` or `"ip"`
`value`	string	Yes	The 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

Remove a single HWID or IP from the blacklist.

Request body

Field	Type	Required	Description
`type`	string	Yes	`"hwid"` or `"ip"`
`value`	string	Yes	The 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

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

Request body

Field	Type	Required	Description
`type`	string	Yes	`"hwid"` or `"ip"`
`value`	string	Yes	The 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

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

Request body

Field	Type	Required	Description
`type`	string	Yes	`"hwid"` or `"ip"`
`value`	string	Yes	The 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

Constraint	Value
Max entries per list	1,000
HWID value max length	128 characters
IP value max length	45 characters (IPv4 and IPv6)
HWID value min length	1 character
IP value min length	7 characters

Evaluation order

During authentication, lists are checked in this order:

IP blacklist (reject if matched)
IP whitelist (reject if list is non-empty and IP not listed)
HWID blacklist (reject if matched)
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.

​Response signature model (Ed25519)

​Success response shape

​Tamper self-ban endpoint (public auth)

​Request modes

​Critical safety rule

​Example (pre-session, blacklist only)

​Example (post-session, full lockout)

​Get security config

​Path parameters

​Example

​Response (200)

​Update security config

​Request body

​Example

​Response (200)

​Errors

​Clearing a list

​Add to blacklist

​Request body

​Example

​Response (200)

​Remove from blacklist

​Request body

​Example

​Response (200)

​Add to whitelist

​Request body

​Example

​Response (200)

​Remove from whitelist

​Request body

​Example

​Response (200)

​Limits

​Evaluation order

Response signature model (Ed25519)

Success response shape

Tamper self-ban endpoint (public auth)

Request modes

Critical safety rule

Example (pre-session, blacklist only)

Example (post-session, full lockout)

Get security config

Path parameters

Example

Response (200)

Update security config

Request body

Example

Response (200)

Errors

Clearing a list

Add to blacklist

Request body

Example

Response (200)

Remove from blacklist

Request body

Example

Response (200)

Add to whitelist

Request body

Example

Response (200)

Remove from whitelist

Request body

Example

Response (200)

Limits

Evaluation order