Blacklists and exclusions

Access rules decide who may validate before anything else is checked:

• A blacklist rule refuses matching license checks with BLACKLISTED: a leaked key used from one machine, a range of addresses that resells keys, a country you don't sell to, or a customer who charged back.
• An exclusion rule lets matching checks through without limits: your own machine or office address while you develop and test, so you never use up a customer's machine slots or trigger overuse alerts.

Rules apply within seconds of saving them and work on every plan, also after a downgrade.

What a rule matches

Type	Value	Blacklist	Exclusion
IP	One address (203.0.113.7, 2001:db8::1) or a CIDR range (203.0.113.0/24, 2001:db8::/32)	✓	✓
Machine (HWID)	The machine id your app sends as fingerprint, hwid or host, exactly	✓	✓
Country	Two-letter ISO code (RU, BR), from Cloudflare's location of the request	✓ (Lite and Standard)
Customer	One of your customers: every license they own	✓

Each rule applies to your whole organization, to one product or to one license. A rule can carry a note and an expiry date, after which it stops matching. Every rule shows how many checks it has matched and when it last did.

In what order

1. The key must exist: an unknown key is NOT_FOUND whatever your rules say.
2. Access rules: of the rules that match, the one with the most specific scope decides (license, then product, then organization). In the same scope an exclusion beats a blacklist, so you can exclude your own machine from an organization-wide country block.
3. A blacklisted check answers BLACKLISTED. It takes no machine slot.
4. An excluded check skips blacklists and the machine limit, takes no slot, raises no overuse alert and is left out of analytics and the license's activity feed. The license must still be active and unexpired, unless the exclusion is set to let suspended and expired licenses through (a revoked license stays revoked).
5. Otherwise the usual checks: status, expiry, machine limit.

What your app sees

BLACKLISTED is a rejection like REVOKED: { "valid": false, "code": "BLACKLISTED" } on /api/v1/validate and HTTP 400 on /api/v2/license/validate, so the official SDKs, V1 ones included, already treat it as "no". The message doesn't say which rule matched.

Adding rules

With the management API (or a personal access token in scripts):

# Block a leaked key's machine, for this license only
curl -X POST https://api.sunlicense.com/api/v1/access-rules \
  -H "Authorization: Bearer $SUNLICENSE_TOKEN" -H "Content-Type: application/json" \
  -d '{"kind":"BLACKLIST","type":"HWID","value":"machine-7f3a","scope":"LICENSE","scopeId":"<license id>","note":"Shared on a forum"}'

# Exclude your own address while you test
curl -s https://api.sunlicense.com/api/v1/access-rules/my-ip -H "Authorization: Bearer $SUNLICENSE_TOKEN"
curl -X POST https://api.sunlicense.com/api/v1/access-rules \
  -H "Authorization: Bearer $SUNLICENSE_TOKEN" -H "Content-Type: application/json" \
  -d '{"kind":"EXCLUSION","type":"IP","value":"198.51.100.23","note":"My office"}'

POST /api/v1/access-rules/import adds up to 1,000 rules in one go (every row or none; rules you already have are skipped). An Access rules page in the dashboard, with "Block this machine" and "Exclude my current IP" buttons and CSV import, is coming next.

Seeing rules needs licenses.read; adding, changing and deleting them needs licenses.write, like revoking a license.

Limits

	Free	Lite	Standard
Rules (blacklists and exclusions together, unexpired)	10	500	Unlimited
Country blacklist		✓	✓

Limits only apply to adding rules. Rules you already have keep working after a downgrade.

Good to know

• Addresses are compared, never stored. The caller's IP is matched against your rules in memory and discarded; SunLicense still keeps no IP addresses of license checks (privacy policy).
• Country blocks are a soft control. A VPN or proxy changes the country a request appears to come from. Use them to stop casual resale in a region, not as a security boundary.
• Exclude an address, not a whole provider. Home connections often change address; for a developer machine a machine (HWID) exclusion is more reliable.
• Merging customers moves their customer rules to the customer that remains.