Policies

Intro

Policies are the building blocks of your custom rule chain. They determine how access is restricted or granted for different users on different pages. For more information, see the policies overview documentation.

Policies use page groups, visitor groups, visit count, CAPTCHA count, and user agent string to determine whether a visit triggers the policy or not. Policies also contain instructions for handling the visit once triggered. For more information, see the visit authorization documentation.

Policy type

{
    "type": "policy",
    "id": "be1f4099-ce63-4d03-963f-c70d893ae287",
    "name": "rate limit",
    "visitor_negated": false,
    "visitor_group_ids": [
        "f98ba027-9b14-4f40-b48c-1ce33ce0284f",
        "79b216e8-500f-489d-8644-d4127e4c2885"
    ],
    "page_group_ids": [
        "5d77371a-9e4a-41cf-8c1a-c8394d105e19"
    ],
    "captcha_status": "NOT_APPLICABLE",
    "num_times": 10,
    "time_interval_num": 10,
    "time_interval_unit": "MINUTES",
    "visit_interval": 1,
    "authorization": "deny",
    "reason": "Too many visits!",
    "priority": 876,
    "enabled": true,
    "description": "",
    "ip_appender": {
        "visitor_group_id": "268087e6-c3f9-484e-aadd-c2195c782603",
        "expiration_time_num": 10,
        "expiration_time_unit": "DAYS"
    },
    "created": 1578018203208,
    "is_default": false
}

Attributes

authorizationstring

The recommended action when policy is triggered.

Options:
  • "allow": Visitor is allowed access.
  • "deny": Visitor is denied access.
  • "captcha": Visitor must complete CAPTCHA for access.
  • "$YOUR_CUSTOM_AUTHORIZATION": You decide what your custom authorization means!
captcha_statusstring

What kind of CAPTCHA events to count for policy.

Options:
  • "FAILED": Matches failed CAPTCHAs.
  • "UNSOLVED": Matches unattempted/ignored CAPTCHAs.
  • "SOLVED": Matches solved CAPTCHAs.
  • "NOT_APPLICABLE": CAPTCHA attempts do not apply to policy.
creatednumber

Timestamp of object creation in milliseconds.

descriptionstring

Internal notes for object.

enabledboolean

Whether policy is enabled. Disabled policies will not be checked.

idstring

Unique identifier for object.

ip_appenderIP Appender

Automatically adds IP address of visitor to a visitor group when policy is triggered. A common use case for IP appender is to automatically blacklist a seriously misbehaving IP address.

is_defaultboolean

Whether the object is a system default. System defaults cannot be modified.

namestring

Unique display name for object.

num_timesnumber

Number of visits/CAPTCHAs required to trigger policy.

page_group_idsarray

List of IDs for page groups that trigger policy.

prioritynumber

Positive number representing policy priority. Policies with higher priority will be checked before those with lower priority.

reasonstring

An explanatory message that can be passed on to the visitor.

time_interval_numnumber

Number for policy time interval. The policy time interval is the amount of time within which visits/CAPTCHAs must occur to trigger policy.

time_interval_unitstring

Unit for policy time interval. The policy time interval is the amount of time within which visits/CAPTCHAs must occur to trigger policy.

Options:
  • "MILLISECONDS"
  • "SECONDS"
  • "MINUTES"
  • "HOURS"
  • "DAYS"
typestring

String representing object type.

always value: "policy"
visit_intervalnumber

Number of visits that must occur before policy can be triggered again. This is only applicable to policies with "captcha" authorization.

visitor_group_idsarray

List of IDs for visitor groups that trigger policy.

visitor_negatedboolean

Whether to trigger when a visitor matches or does not match visitor group.

List policies

GET/gatekeeper/policies

Example

Request

curl "https://api.nettoolkit.com/v1/gatekeeper/policies" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"

Response

{
    "code": 1000,
    "results": [
        {
            "type": "policy",
            "id": "a9991a07-6b64-4eab-88ab-4f27212322c1",
            "name": "restricted access",
            "visitor_negated": false,
            "visitor_group_ids": [
                "f98ba027-9b14-4f40-b48c-1ce33ce0284f"
            ],
            "page_group_ids": [
                "0d6b66c5-afbc-3cd8-ab27-90167a4ba028"
            ],
            "captcha_status": "NOT_APPLICABLE",
            "num_times": 30,
            "time_interval_num": 1,
            "time_interval_unit": "HOURS",
            "priority": 900,
            "authorization": "captcha",
            "reason": "Prove you're human.",
            "visit_interval": 100,
            "enabled": true,
            "description": "",
            "created": 1578018203208,
            "is_default": false
        }
    ]
}

Other types

IP Appender

{
    "visitor_group_id": "268087e6-c3f9-484e-aadd-c2195c782603",
    "expiration_time_num": 10,
    "expiration_time_unit": "DAYS"
}

Attributes

expiration_time_intervalstring

Unit for expiration time. The expiration time is the amount of time an IP address added via the IP appender should remain in the target visitor group before being removed.

Options:
  • "MINUTES"
  • "HOURS"
  • "DAYS"
expiration_time_numnumber

Number for expiration time. The expiration time is the amount of time an IP address added via the IP appender should remain in the target visitor group before being removed.

visitor_group_idstring

Unique identifier for visitor group to which visitor IP address is added.