Visitor Groups

Intro

A visitor group is a set of classifications used to identify users visiting your application. Available visitor classifications include IP address/range, organization, tag, location, and user ID. For more information, see the visitor types documentation.

A visitor is a valid member of its visitor type. For example, "1.2.3.4" is a valid IP visitor, but not a valid organization visitor.

Visitor groups are used by policies to determine if a visit triggers that policy. One visitor group can be used by multiple policies.

Visitor Groups object

Sample object

{
    "type": "visitor_group",
    "id": "71ba3946-bdb8-45f4-9118-9fc3d5790bb3",
    "name": "whitelisted IPs",
    "visitor_type": "IP",
    "visitors": [
        {
            "type": "visitor",
            "visitor_group_id": "71ba3946-bdb8-45f4-9118-9fc3d5790bb3",
            "value": "1.2.3.4",
            "created": 1578018203208,
            "creator_type": "USER",
            "creator_id": "05063cca-dede-485d-be3c-c7899b9d737c"
        }
    ],
    "visitors_pagination": {
        "has_more": false,
        "url": "/v1/gatekeeper/visitor-groups/71ba3946-bdb8-45f4-9118-9fc3d5790bb3/visitors"
    },
    "operator": null,
    "created": 1578018203208,
    "is_default": false
}

Attributes

typestring

String representing object type.

always value: "visitor_group"
idstring

Unique identifier for object.

namestring

Unique display name for object.

visitor_typestring

String representing how visitors are matched for this group.

Options:
  • "IP": Match visitors with this IP address or in this IP range.
  • "ORGANIZATION": Match visitors from this organization.
  • "TAG": Match visitors with this tag.
  • "COUNTRY": Match visitors from this country.
  • "USER_ID": Match visitors in this user ID set.
  • "DEFAULT": Match all visitors (used by default visitor group).
visitorsarray

List of visitors associated with this object. Limited to 20 results.

visitors[].typestring

String representing object type.

always value: "visitor"
visitors[].visitor_group_idstring

ID of visitor group that owns this object.

visitors[].valuestring

Value for object. The value should be a valid member of its visitor type.

Valid visitors by type:

  • IP: a valid IP address or range. IP addresses should be in IPv4 dot notation. For example, "1.2.3.4" or "99.200.55.3". IP ranges should be in CIDR notation. For example, "1.2.3.0/24" represents all IP addresses between 1.2.3.0 and 1.2.3.255.
  • ORGANIZATION: a recognized organization name. Organization names are derived from regional Internet registry data, and provided as is. For example, "Google, LLC".
  • TAG: a recognized tag value. For example, "data center" or "ISP".
  • COUNTRY: a recognized country name. Country names are provided by Java's Locale class. For example, "United States".
  • USER_ID: a positive 8-byte number in string format. For example, "99" is valid, "-22" is not. When authorizing visits, anonymous visitors will be treated as if they have user ID "0".
visitors[].creatednumber

Timestamp of object creation in milliseconds.

visitors_paginationobject

Meta data for paginating visitors list. This is a standard pagination object. More information available here.

operatorstring

The operator for advanced handling of user IDs. Only available for user ID type visitor groups.

Options:
  • "in": Match user IDs in this set.
  • "between": Match user IDs between two value. Range is checked inclusively (id >= lower bounds, id <= upper bounds).
  • "less": Match user IDs less than this value. Number is checked exclusively (id > number).
  • "greater": Match user IDs greater than this value. Number is checked exclusively (id > number).
creatednumber

Timestamp of object creation in milliseconds.

is_defaultboolean

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

Endpoints

List visitor groups

Results are ordered by creation time, from newest to oldest.

GET/gatekeeper/visitor-groups

Examples

Example Request
curl -s -H "X-NTK-KEY: $your_key_here" \
"https://api.nettoolkit.com/v1/gatekeeper/visitor-groups"
Example Response
{
    "code": 1000,
    "results": [
        {
            "type": "visitor_group",
            "id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "name": "North America",
            "visitor_type": "COUNTRY",
            "visitors": [
                {
                    "type": "visitor",
                    "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
                    "value": "United States",
                    "created": 1578018203208
                }
            ],
            "visitors_pagination": {
                "has_more": false,
                "url": "/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors"
            },
            "created": 1578018203208,
            "is_default": false
        }
    ]
}

List visitors in visitor group

Results are ordered by visitor value alphabetically.

GET/gatekeeper/visitor-groups/:visitor_group_id/visitors

Parameters

limitnumber

Limit the number of objects returned.

default value: 20
value_afterstring

Only return objects after this value alphabetically. This parameter can be used for pagination.

Examples

Example Request
curl -s -H "X-NTK-KEY: $your_key_here" \
"https://api.nettoolkit.com/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors"
Example Response
{
    "code": 1000,
    "results": [
        {
            "type": "visitor",
            "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "value": "Canada",
            "created": 1578018203208
        }
    ],
    "pagination": {
        "has_more": false,
        "url": "/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors"
    }
}

Add visitor to visitor group

POST/gatekeeper/visitor-groups/:visitor_group_id/visitors

Parameters

visitor(required)string

Value of visitor to add. Value must be a valid member of visitor group type.

Examples

Example Request
curl -s -H "X-NTK-KEY: $your_key_here" -d "visitor=Canada" \
"https://api.nettoolkit.com/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors"
Example Response
{
    "code": 1000,
    "results": [
        {
            "type": "visitor",
            "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "value": "Canada",
            "created": 1578018203208
        }
    ]
}

Remove visitor from visitor group

DELETE/gatekeeper/visitor-groups/:visitor_group_id/visitors

Parameters

visitor(required)string

Value of visitor to add. Value must be a valid member of visitor group type.

Examples

Example Request
curl -s -H "X-NTK-KEY: $your_key_here" -d "visitor=Canada" \
"https://api.nettoolkit.com/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors"
Example Response
{
    "code": 1000,
    "results": [
        {
            "type": "visitor",
            "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "value": "Canada",
            "created": 1578018203208
        }
    ]
}