Policies

Contents

  • Intro
  • Policies object
  • Endpoints

    • 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.

    Policies object

    Sample object

    {
    "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

    typestring

    String representing object type.

    always value: "policy"
    idstring

    Unique identifier for object.

    namestring

    Unique display name for object.

    visitor_negatedboolean

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

    visitor_group_idsarray

    List of IDs for visitor groups that trigger policy.

    page_group_idsarray

    List of IDs for page groups that trigger policy.

    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.
    num_timesnumber

    Number of visits/CAPTCHAs required to trigger policy.

    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"
    visit_intervalnumber

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

    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!
    reasonstring

    An explanation message that can be passed on the the visitor.

    prioritynumber

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

    enabledboolean

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

    descriptionstring

    Internal notes for object.

    ip_appenderobject

    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.

    ip_appender.visitor_group_idstring

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

    ip_appender.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.

    ip_appender.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"
    creatednumber

    Timestamp of object creation in milliseconds.

    is_defaultboolean

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

    Endpoints

    List policies

    GET/gatekeeper/policies

    Examples

    Example Request
    curl "https://api.nettoolkit.com/v1/gatekeeper/policies" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"
    Example 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
        }
    ]
}