> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authforge.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Blacklists & Whitelists

> Control which devices and IPs can authenticate with your AuthForge app using blacklists and 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.

```mermaid theme={null}
flowchart TD
    A["SDK sends /auth/validate"] --> B{"IP blacklisted?"}
    B -->|Yes| X["Reject: blocked"]
    B -->|No| C{"IP whitelist active?"}
    C -->|Yes, IP not listed| X
    C -->|No, or IP listed| D{"HWID blacklisted?"}
    D -->|Yes| X
    D -->|No| E{"HWID whitelist active?"}
    E -->|Yes, HWID not listed| X
    E -->|No, or HWID listed| F["Continue to license validation"]
```

### 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

```bash theme={null}
# 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

<Warning>
  Enabling a HWID whitelist blocks ALL devices not explicitly listed. Make sure you've added all expected HWIDs before enabling.
</Warning>

## 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:**

```bash theme={null}
curl https://api.authforge.cc/v1/apps/YOUR_APP_ID/security \
  -H "Authorization: Bearer af_live_your_key"
```

```json theme={null}
{
  "hwidBlacklist": ["a1b2c3d4..."],
  "hwidWhitelist": [],
  "ipBlacklist": ["203.0.113.50"],
  "ipWhitelist": []
}
```

**Replace entire security config:**

```bash theme={null}
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:**

```bash theme={null}
# 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:

```json theme={null}
{
  "status": "failed",
  "error": "blocked"
}
```

The SDK treats this as a login failure. See [SDK Best Practices](/sdk/best-practices#error-handling-on-login) for guidance on user-facing error messages.

## Next steps

* [Security API Reference](/api/security); Full endpoint documentation
* [Security Best Practices](/best-practices/security); Hardening your AuthForge integration