Overview
Conditional access rules checked on validation: version, time window, IP range, or a required variable.
Rules add extra conditions to a validation. Beyond "is this key valid", a rule can require a minimum
version, a time window, an allowed network, or a variable to be present. When a rule rejects a key,
validation returns valid: false with the rule's message.
This extension depends on core. The require_variable type also uses
the Variables extension. See the
API Reference for the endpoints. Rules have no config
file of their own.
Rule types
| Type | Checks | Common config |
|---|---|---|
version | A version field on the request | min, max, equals, values, and the field to read (defaults to version). |
time_window | The current time | after, before (dates), and days (days of the week). |
ip_cidr | The caller's IP | cidr or cidrs (one or more CIDR ranges). |
country | The caller's country, from their IP | values: a list of ISO country codes, e.g. ["US", "CA"]. |
region | The caller's region/subdivision, from their IP | values: a list of subdivision codes, e.g. ["US-CA"] uses the CA part. |
asn | The caller's network operator, from their IP | values: a list of ASN numbers, e.g. [13335, 15169]. |
hwid | A hardware ID your software sends | values: a list of allowed IDs; header (defaults to hwid) or a body field to read it from. |
require_variable | A variable on the license | key, and an optional equals. |
Each rule also has an action, allow or deny (default deny), and an optional message
shown when it rejects a key. A deny rule rejects when it matches; an allow rule rejects when it
does not match. Together these give you a whitelist (allow) and a blacklist (deny) for
any attribute: country, region, ASN, IP range, or hardware ID.
country, region, and asn resolve the caller's IP with Kora's GeoLite2 databases, which core
downloads on startup (see the Geo settings). If a
database isn't present, or the IP can't be located, that rule is skipped rather than rejecting the
request, so a missing database never locks out an allow rule. hwid matches a hardware ID your
software sends as a request header (Kora can't read it from the connection).
Applying rules
- Attach a rule to one or more products, or mark it global so it applies to every product.
- Rules are evaluated on every validation for the product. The first rule to reject wins.
Rules are managed from the Rules dashboard page, the rules console command, or the
API.
Examples
A rule that only allows version 2.0.0 and up (a whitelist):
{
"name": "min-version",
"type": "version",
"action": "allow",
"config": { "min": "2.0.0" },
"message": "Please update to version 2.0.0 or newer."
}A rule that blocks two countries (a blacklist):
{
"name": "block-regions",
"type": "country",
"action": "deny",
"config": { "values": ["RU", "CN"] },
"message": "This product is not available in your region."
}A rule that binds a key to known devices (a hardware-ID whitelist). Your software sends the ID as the
hwid request header:
{
"name": "known-devices",
"type": "hwid",
"action": "allow",
"config": { "values": ["A1B2-C3D4", "E5F6-G7H8"] }
}