Access Control allows you to whitelist and/or blacklist specific bots, IP addresses, and access methods according to customized rules.
Custom Rules can contain multiple conditions and categories. Only when all of the rules conditions match (using the AND operator) the action (whitelist/blacklist/hard block) is executed.

The Custom Rules API allows you to configure whitelisting and blacklisting rules via API calls.

For more information on configuring Access Control and Custom Rules, see Access Control.

Requests

Requests must be sent over HTTPS using a content type of application/json and include the Authorization header that is used for authentication.

Header	Description
Authorization	Token to provide authentication
Content-Type	Value is always application/json

All requests are made to the base URL of https://console.perimeterx.com/api/v1/custom_rules

Authentication

In order to access the PerimeterX Custom Rules API, you are required to present an authentication token in the HTTP Authorization header.

The following is an example:

Authorization: Bearer <TOKEN>

Authentication tokens can be generated in the PerimeterX Portal (https://console.perimeterx.com/). For more information see Managing Applications .

Endpoints

Create custom rule

HTTP Method	Request URL
POST	https://console.perimeterx.com/api/v1/custom_rules

Parameters

Parameter	Description
description	rule description
type	["none", "blacklist", "whitelist", "hardblock"]
conditions	list of conditions

Request Schema

{
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      },
      "type": {
        "enum": ["none", "blacklist", "whitelist", "hardblock"]
      },
      "conditions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "category": {
              "enum": ["ua", "ips", "ipRanges", "domain", "trueIps", "trueIpRanges", "url", "custom_param1", "custom_param2", "custom_param3", "custom_param4", "custom_param5", "custom_param6", "custom_param7", "custom_param8", "custom_param9", "custom_param10"]
            },
            "value": {
              "type": [
                "string",
                "object"
              ],
              "properties": {
                "option": {
                  "enum": ["prefix", "exact", "suffix", "contains", "regex"]
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "option",
                "value"
              ]
            }
          }
        }
      }
    },
    "required": [
      "description",
      "type",
      "conditions"
    ]
  }

Request Example

curl -X POST
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       -d '{
        "description": "custom rule description",
        "type": "blacklist",
        "conditions": [{"category":"ips","value":"1.1.1.1"},{"category":"domain","value":{"option":"exact","value":"example.com"}}]
        }'
        "https://console.perimeterx.com/api/v1/custom_rules"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "custom rule description",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        }
      ]
    },
    "message": "success"
  }

Update custom rule by rule id

HTTP Method	Request URL
PUT	https://console.perimeterx.com/api/v1/custom_rules/:rule_id

Parameters

Parameter	Description
rule_id (query)	Rule ID. This can be obtained from the Portal Policy section
description	rule description
type	["none", "blacklist", "whitelist", "hardblock"]
conditions	list of conditions

Request Schema

{
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      },
      "type": {
        "enum": ["none", "blacklist", "whitelist", "hardblock"]
      },
      "conditions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "category": {
              "enum": ["ua", "ips", "ipRanges", "domain", "socketIps", "socketIpRanges", "url", "custom_param1", "custom_param2", "custom_param3", "custom_param4", "custom_param5", "custom_param6", "custom_param7", "custom_param8", "custom_param9", "custom_param10"]
            },
            "value": {
              "type": [
                "string",
                "object"
              ],
              "properties": {
                "option": {
                  "enum": ["prefix", "exact", "suffix", "contains", "regex"]
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "option",
                "value"
              ]
            }
          }
        }
      }
    },
    "required": [
      "description",
      "type",
      "conditions"
    ]
  }

Request Example

curl -X POST
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       -d '{
        "description": "updated custom rule description",
        "type": "blacklist",
        "conditions": [{"category":"ips","value":"1.1.1.1"},{"category":"domain","value":{"option":"exact","value":"example.com"}}]
        }'
        "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "updated custom rule description",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        }
      ]
    },
    "message": "success"
  }

Delete custom rule by rule id

HTTP Method	Request URL
DELETE	https://console.perimeterx.com/api/v1/custom_rules/:rule_id

Parameters

Parameter	Description
rule_id	Rule ID. It can be obtained from portal policy view

Request Example

curl -X DELETE
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "string"
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": "success",
    "message": "success"
  }

HTTP Method	Request URL
GET	https://console.perimeterx.com/api/v1/custom_rules/:rule_id

Parameters

Parameter	Description
rule_id	Rule ID. It can be obtained from portal policy view

Request Example

curl -X GET
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "custom rule 1",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ua",
          "value": "PhantomJS"
        },
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        },
        {
          "category": "custom_param1",
          "value": "test"
        }
      ]
    },
    "message": "success"
  }

Get all custom rules

HTTP Method	Request URL
GET	https://console.perimeterx.com/api/v1/custom_rules

Request Example

.. code-block:: shell

curl -X GET
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "conditions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string"
                  },
                  "value": {
                    "type": [
                      "string",
                      "object"
                    ],
                    "properties": {
                      "option": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "option",
                      "value"
                    ]
                  }
                }
              }
            }
          },
          "required": [
            "id",
            "description",
            "type",
            "conditions"
          ]
        }
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": [
      {
        "id": "a596bc02-1189-48b1-9cf2-12001495754e",
        "description": "custom rule 1",
        "type": "blacklist",
        "conditions": [
          {
            "category": "ua",
            "value": "PhantomJS"
          },
          {
            "category": "ips",
            "value": "1.1.1.1"
          },
          {
            "category": "domain",
            "value": {
              "option": "exact",
              "value": "example.com"
            }
          }
        ]
      },
      {
        "id": "46a49376-042d-4ccd-96e4-4f753a6d0930",
        "description": "custom rule 2",
        "type": "none",
        "conditions": [
          {
            "category": "ips",
            "value": "2.2.2.2"
          }
        ]
      }
    ],
    "message": "success"
  }

Error Messages and Codes

The Custom rules API returns error messages in JSON format.

Example

{
    "result": false,
    "message": "Invalid authorization token"
  }

The following table describes the codes which may appear when working with the API.

Status Code	Text	Description
400	Request object not valid	The request structure may be invalid
400	Invalid request	The request structure may be invalid
400	Invalid authorization Token	The Authorization header : Bearer is missing or invalid
400	Custom rule id does not exist	Custom rule id does not exist
400	Custom rule has invalid value	Custom rule id is not a valid UUID
400	Description field value is missing	Description has no value (mandatory field)
400	Type field value is missing	Type has no value (mandatory field)