Blacklists

Blacklists let you block specific hardware IDs (HWIDs) or IP addresses at the product level. Blocked values are checked during license authorization before policy evaluation — if a blacklisted HWID or IP is detected, the request is denied immediately.

How It Works

  1. You add a HWID or IP to a product's blacklist
  2. Values are hashed (SHA-256) and stored alongside the original for display
  3. During /v1/licenses/authorize, the provided HWID and IP are checked against the blacklist
  4. If a match is found, authorization is denied with HWID_BLACKLISTED or IP_BLACKLISTED

Managing Blacklists

List Entries

GET /v1/dashboard/blacklists/products/:productId?type=HWID|IP

Filter by type to see only HWID or IP entries.

Add an Entry

await fetch('/v1/dashboard/blacklists/products/PRODUCT_ID', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'HWID',                    // or 'IP'
    value: 'banned-hardware-id',
    reason: 'Chargeback fraud'       // Optional
  })
});

If the value already exists, it's updated (upserted) with the new reason.

Bulk Add

Add up to 200 entries in a single request:

await fetch('/v1/dashboard/blacklists/products/PRODUCT_ID/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entries: [
      { type: 'HWID', value: 'hwid-1', reason: 'Ban wave' },
      { type: 'HWID', value: 'hwid-2', reason: 'Ban wave' },
      { type: 'IP', value: '192.168.1.100', reason: 'Abuse' }
    ]
  })
});

Remove an Entry

DELETE /v1/dashboard/blacklists/products/:productId/:entryId

Authorization Denial

When a blacklisted value is detected during license authorization:

{
  "ok": false,
  "allow": false,
  "reasonCode": "HWID_BLACKLISTED",
  "message": "Chargeback fraud"
}

The message field contains the reason you provided when adding the entry (or a default message if no reason was given).

Use Cases

  • Chargeback fraud — block the HWID of users who issue chargebacks
  • License sharing — block HWIDs of known unauthorized users
  • Abuse prevention — block IPs used for automated abuse
  • Regional blocking — block IP ranges (though region-based IP limiting may be more appropriate)

Limits

  • Value: max 500 characters
  • Reason: max 500 characters
  • Bulk add: max 200 entries per request