Client Ban Policy - Apinizer Dokümantasyonu

General Information

Policy Type

policy-client-banner

Endpoints

List Policies

GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/

Add Policy

POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Update Policy

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Delete Policy

DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

List Policies

Endpoint

GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/

Request

Headers

Header	Value
Authorization	Bearer `{token}`

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "resultList": [
    {
      "apiProxy": {
        "name": "MyAPI",
        "requestPolicyList": [
          {
            "type": "policy-client-banner",
            "name": "client-ban-policy",
            "description": "Ban clients exceeding error threshold",
            "active": true,
            "clientIdentityVariableList": [
              {
                "type": "HEADER",
                "headerName": "X-API-Key"
              }
            ],
            "thresholdWindowInSeconds": 10,
            "thresholdCountPerWindow": 5,
            "thresholdCalculationType": "COUNT",
            "banTimeInSeconds": 300,
            "enableRetryAfterHeader": true,
            "ignoreWhenKeyIsEmpty": false,
            "assertionCondition": {
              "criteria": "IF_ANY_MATCH",
              "rules": [
                {
                  "variable": {
                    "type": "HTTP_STATUS_CODE"
                  },
                  "comparisonOperator": "GE",
                  "value": "400",
                  "valueSource": "STATIC"
                }
              ]
            }
          }
        ],
        "responsePolicyList": [],
        "errorPolicyList": []
      }
    }
  ],
  "resultCount": 1
}

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Add Policy

Endpoint

POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header	Value
Authorization	Bearer `{token}`
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name
policyName	string	Yes	Policy name (must match name in body)

Request Body

Important: The request body must follow the PolicyOperationDTO structure with separate operationMetadata and policy objects. See Add Policy for the general structure.

Full JSON Body Example - Basic Client Ban

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-client-banner",
    "name": "client-ban-policy",
    "description": "Ban clients exceeding error threshold",
    "active": true,
    "clientIdentityVariableList": [
      {
        "type": "HEADER",
        "headerName": "X-API-Key"
      }
    ],
    "thresholdWindowInSeconds": 10,
    "thresholdCountPerWindow": 5,
    "thresholdCalculationType": "COUNT",
    "banTimeInSeconds": 300,
    "enableRetryAfterHeader": true,
    "ignoreWhenKeyIsEmpty": false,
    "assertionCondition": {
      "criteria": "IF_ANY_MATCH",
      "rules": [
        {
          "variable": {
            "type": "HTTP_STATUS_CODE"
          },
          "comparisonOperator": "GE",
          "value": "400",
          "valueSource": "STATIC"
        }
      ]
    },
    "condition": {
      "criteria": "ALWAYS",
      "rules": []
    }
  }
}

Full JSON Body Example - IP-Based Ban with Percentage Threshold

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-client-banner",
    "name": "ip-ban-policy",
    "description": "Ban IPs with high error percentage",
    "active": true,
    "clientIdentityVariableList": [
      {
        "type": "CLIENT_IP"
      }
    ],
    "thresholdWindowInSeconds": 60,
    "thresholdCountPerWindow": 50,
    "thresholdCalculationType": "PERCENT",
    "banTimeInSeconds": 600,
    "enableRetryAfterHeader": true,
    "ignoreWhenKeyIsEmpty": false,
    "assertionCondition": {
      "criteria": "IF_ANY_MATCH",
      "rules": [
        {
          "variable": {
            "type": "HTTP_STATUS_CODE"
          },
          "comparisonOperator": "GE",
          "value": "500",
          "valueSource": "STATIC"
        }
      ]
    },
    "condition": {
      "criteria": "ALWAYS",
      "rules": []
    }
  }
}

Full JSON Body Example - Multi-Variable Client Ban

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-client-banner",
    "name": "multi-variable-ban",
    "description": "Ban clients using multiple identity variables",
    "active": true,
    "clientIdentityVariableList": [
      {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      {
        "type": "CLIENT_IP"
      }
    ],
    "thresholdWindowInSeconds": 30,
    "thresholdCountPerWindow": 10,
    "thresholdCalculationType": "COUNT",
    "banTimeInSeconds": 1800,
    "enableRetryAfterHeader": true,
    "ignoreWhenKeyIsEmpty": false,
    "assertionCondition": {
      "criteria": "IF_ALL_MATCH",
      "rules": [
        {
          "variable": {
            "type": "HTTP_STATUS_CODE"
          },
          "comparisonOperator": "EQ",
          "value": "401",
          "valueSource": "STATIC"
        },
        {
          "variable": {
            "type": "REQUEST_PATH"
          },
          "comparisonOperator": "CONTAINS",
          "value": "/auth",
          "valueSource": "STATIC"
        }
      ]
    },
    "condition": {
      "criteria": "ALWAYS",
      "rules": []
    }
  }
}

Request Body Fields

The request body has two top-level fields:

Field	Type	Required	Description
operationMetadata	object	Yes	Operation metadata. See Policy Operation Metadata
policy	object	Yes	Policy configuration (see below)

Common Policy Fields (policy object)

Field	Type	Required	Default	Description
type	string	Yes	-	Policy type: `policy-client-banner`
name	string	Yes	-	Policy name (must match path parameter)
description	string	No	-	Policy description
active	boolean	No	true	Whether policy is active
condition	object	Yes	-	Policy condition

Client Ban Specific Fields

Field	Type	Required	Default	Description
clientIdentityVariableList	array	Yes	[]	List of variables used to identify clients
thresholdWindowInSeconds	integer	Yes	10	Time window in seconds for threshold calculation
thresholdCountPerWindow	integer	Yes	1	Threshold count or percentage per window
thresholdCalculationType	string	Yes	COUNT	Threshold calculation type
banTimeInSeconds	integer	Yes	10	Duration to ban client in seconds
enableRetryAfterHeader	boolean	No	false	Enable Retry-After header in ban response
ignoreWhenKeyIsEmpty	boolean	No	false	Ignore requests when identity key is empty
assertionCondition	object	Yes	-	Condition that triggers ban counting

EnumErrorThresholdType (thresholdCalculationType)

COUNT - Count-based threshold (number of errors)
PERCENT - Percentage-based threshold (percentage of errors)

VariableDTO (clientIdentityVariableList item)

Field	Type	Required	Description
type	string	Yes	Variable type
headerName	string	No*	Header name (required if type=HEADER)
paramName	string	No*	Parameter name (required if type=PARAMETER)
contextValue	string	No*	Context value (required if type=CONTEXT_VALUES)

Variable Types

HEADER - Extract from HTTP header
PARAMETER - Extract from query/path/form parameter
BODY - Extract from request/response body (XML, JSON, or raw)
CONTEXT_VALUES - Extract from system context values (e.g., REQUEST_REMOTE_ADDRESS for client IP)
CLIENT_IP - Client IP address
CUSTOM - Extract using custom script

Note: For client IP, use type=CLIENT_IP or type=CONTEXT_VALUES with contextValue=REQUEST_REMOTE_ADDRESS.

PolicyConditionDTO (assertionCondition)

Field	Type	Required	Description
criteria	string	Yes	Condition criteria
rules	array	Yes	List of condition rules

EnumConditionCriteria (assertionCondition.criteria)

ALWAYS - Always count
IF_ALL_MATCH - Count if all rules match
IF_ANY_MATCH - Count if any rule matches (common for error conditions)
IF_NONE_MATCH - Count if no rules match

ConditionRuleDTO (assertionCondition.rules item)

Field	Type	Required	Description
variable	object	Yes	Variable to check
comparisonOperator	string	Yes	Comparison operator
value	string	Yes	Value to compare against
valueSource	string	No	Value source

EnumConditionValueComparisonOperator (comparisonOperator)

LT - Less than
LE - Less than or equal to
GT - Greater than
GE - Greater than or equal to
EQ - Equal to
NE - Not equal to
EQ_IGNORE_CASE - Equal to, case insensitive (string only)
NE_IGNORE_CASE - Not equal to, case insensitive (string only)
STARTS_WITH - Starts with (string only)
NOT_STARTS_WITH - Does not start with (string only)
STARTS_WITH_IGNORE_CASE - Starts with, case insensitive (string only)
NOT_STARTS_WITH_IGNORE_CASE - Does not start with, case insensitive (string only)
ENDS_WITH - Ends with (string only)
NOT_ENDS_WITH - Does not end with (string only)
ENDS_WITH_IGNORE_CASE - Ends with, case insensitive (string only)
NOT_ENDS_WITH_IGNORE_CASE - Does not end with, case insensitive (string only)
CONTAINS - Contains (string only)
NOT_CONTAINS - Does not contain (string only)
CONTAINS_IGNORE_CASE - Contains, case insensitive (string only)
NOT_CONTAINS_IGNORE_CASE - Does not contain, case insensitive (string only)
IS_EXISTS - Variable exists (regardless of value)
IS_NOT_EXISTS - Variable does not exist
IS_NOT_EMPTY - Variable exists and is not empty
IS_EMPTY - Variable does not exist or is empty
EXISTS_AND_EMPTY - Variable exists but is empty
IN - Value is in list
NOT_IN - Value is not in list
IN_IGNORE_CASE - Value is in list, case insensitive (string only)
NOT_IN_IGNORE_CASE - Value is not in list, case insensitive (string only)

EnumConditionValueSource (valueSource)

STATIC - Compare with a constant value
VARIABLE - Compare with another variable

PolicyOperationMetadataDTO (operationMetadata)

Field	Type	Required	Description
targetScope	string	Yes	Target scope
targetEndpoint	string	No	Target endpoint path (if targetScope is ENDPOINT)
targetEndpointHTTPMethod	string	No	Target endpoint HTTP method (if targetScope is ENDPOINT)
targetPipeline	string	Yes	Target pipeline
deploy	boolean	No	true	Whether to deploy immediately
deployTargetEnvironmentNameList	array	No	[]	List of environment names to deploy to
order	integer	No	-	Policy execution order

EnumPolicyTargetScope (operationMetadata.targetScope)

ALL - Apply to entire API Proxy
ENDPOINT - Apply to specific endpoint
GLOBAL - Apply globally

EnumPolicyTargetPipeline (operationMetadata.targetPipeline)

REQUEST - Request pipeline
RESPONSE - Response pipeline
ERROR - Error pipeline

Notes

clientIdentityVariableList must contain at least one variable.
thresholdWindowInSeconds must be greater than 0.
thresholdCountPerWindow must be greater than 0.
thresholdCalculationType is required.
banTimeInSeconds must be greater than 0.
assertionCondition is required and defines when to count errors.
clientIdentityVariableList can contain multiple variables (ban applies if any matches).
ignoreWhenKeyIsEmpty: true skips banning when identity key is empty.
enableRetryAfterHeader: true adds Retry-After header to ban responses.

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "resultList": null,
  "resultCount": null,
  "deploymentResult": {
    "envName": "production",
    "podName": "",
    "podIp": "",
    "success": true,
    "detail": "",
    "responseTime": 123,
    "detailList": []
  }
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/client-ban-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": true,
      "deployTargetEnvironmentNameList": ["production"],
      "order": 1
    },
    "policy": {
      "type": "policy-client-banner",
      "name": "client-ban-policy",
      "description": "Ban clients exceeding error threshold",
      "active": true,
      "clientIdentityVariableList": [
        {
          "type": "HEADER",
          "headerName": "X-API-Key"
        }
      ],
      "thresholdWindowInSeconds": 10,
      "thresholdCountPerWindow": 5,
      "thresholdCalculationType": "COUNT",
      "banTimeInSeconds": 300,
      "enableRetryAfterHeader": true,
      "ignoreWhenKeyIsEmpty": false,
      "assertionCondition": {
        "criteria": "IF_ANY_MATCH",
        "rules": [
          {
            "variable": {
              "type": "HTTP_STATUS_CODE"
            },
            "comparisonOperator": "GE",
            "value": "400",
            "valueSource": "STATIC"
          }
        ]
      },
      "condition": {
        "criteria": "ALWAYS",
        "rules": []
      }
    }
  }'

Update Policy

Endpoint

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header	Value
Authorization	Bearer `{token}`
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name
policyName	string	Yes	Policy name (must match name in body)

Request Body

Note: Request body structure is the same as Add Policy. All fields should be provided for update.

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "resultList": null,
  "resultCount": null,
  "deploymentResult": {
    "envName": "production",
    "podName": "",
    "podIp": "",
    "success": true,
    "detail": "",
    "responseTime": 123,
    "detailList": []
  }
}

Delete Policy

Endpoint

DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header	Value
Authorization	Bearer `{token}`

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name
policyName	string	Yes	Policy name

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "resultList": null,
  "resultCount": null,
  "deploymentResult": {
    "envName": "production",
    "podName": "",
    "podIp": "",
    "success": true,
    "detail": "",
    "responseTime": 123,
    "detailList": []
  }
}

Notes and Warnings

Client Banning:
- Automatically bans clients that exceed error threshold
- Uses identity variables to identify clients
- Banned clients are blocked for specified duration
Threshold Calculation:
- COUNT - Count-based (number of errors)
- PERCENT - Percentage-based (percentage of errors)
- Threshold is calculated within thresholdWindowInSeconds
Identity Variables:
- clientIdentityVariableList identifies clients to ban
- Can use multiple variables (ban applies if any matches)
- Common: API key (HEADER), IP address (CLIENT_IP), user ID (VARIABLE)
Assertion Condition:
- Defines when to count errors/failures
- Common: HTTP status code >= 400 or == 401
- Use IF_ANY_MATCH for multiple error conditions
Ban Duration:
- banTimeInSeconds - Duration to ban client
- Banned clients receive error response during ban period
- Ban automatically expires after duration
Retry-After Header:
- enableRetryAfterHeader: true adds Retry-After header
- Tells clients when they can retry
- Useful for client-side handling
Empty Keys:
- ignoreWhenKeyIsEmpty: true skips banning when identity key is empty
- Useful when identity variable may be missing
Time Window:
- thresholdWindowInSeconds - Time window for threshold calculation
- Errors are counted within this window
- Window slides continuously
Performance:
- Uses cache to track ban status
- Multiple identity variables increase cache usage
- Consider cache performance for high-throughput scenarios
Deployment: Policy changes require deployment to take effect. Set deploy: true in operationMetadata or deploy manually.

List Policies - List all policies
Add Policy - General policy addition guide
Update Policy - General policy update guide
Delete Policy - General policy deletion guide
Blocked IP List Policy - Static IP blocking policy

Home

​General Information

​Policy Type

​Endpoints

​List Policies

​Add Policy

​Update Policy

​Delete Policy

​List Policies

​Endpoint

​Request

​Headers

​Path Parameters

​Response

​Success Response (200 OK)

​cURL Example

​Add Policy

​Endpoint

​Request

​Headers

​Path Parameters

​Request Body

Full JSON Body Example - Basic Client Ban

Full JSON Body Example - IP-Based Ban with Percentage Threshold

Full JSON Body Example - Multi-Variable Client Ban

​Request Body Fields

Common Policy Fields (policy object)

Client Ban Specific Fields

​EnumErrorThresholdType (thresholdCalculationType)

​VariableDTO (clientIdentityVariableList item)

​Variable Types

​PolicyConditionDTO (assertionCondition)

​EnumConditionCriteria (assertionCondition.criteria)

​ConditionRuleDTO (assertionCondition.rules item)

​EnumConditionValueComparisonOperator (comparisonOperator)

​EnumConditionValueSource (valueSource)

​PolicyOperationMetadataDTO (operationMetadata)

​EnumPolicyTargetScope (operationMetadata.targetScope)

​EnumPolicyTargetPipeline (operationMetadata.targetPipeline)

​Notes

​Response

​Success Response (200 OK)

​cURL Example

​Update Policy

​Endpoint

​Request

​Headers

​Path Parameters

​Request Body

​Response

​Success Response (200 OK)

​Delete Policy

​Endpoint

​Request

​Headers

​Path Parameters

​Response

​Success Response (200 OK)

​Notes and Warnings

​Related Documentation

General Information

Policy Type

Endpoints

List Policies

Add Policy

Update Policy

Delete Policy

List Policies

Endpoint

Request

Headers

Path Parameters

Response

Success Response (200 OK)

cURL Example

Add Policy

Endpoint

Request

Headers

Path Parameters

Request Body

Request Body Fields

EnumErrorThresholdType (thresholdCalculationType)

VariableDTO (clientIdentityVariableList item)

Variable Types

PolicyConditionDTO (assertionCondition)

EnumConditionCriteria (assertionCondition.criteria)

ConditionRuleDTO (assertionCondition.rules item)

EnumConditionValueComparisonOperator (comparisonOperator)

EnumConditionValueSource (valueSource)

PolicyOperationMetadataDTO (operationMetadata)

EnumPolicyTargetScope (operationMetadata.targetScope)

EnumPolicyTargetPipeline (operationMetadata.targetPipeline)

Notes

Response

Success Response (200 OK)

cURL Example

Update Policy

Endpoint

Request

Headers

Path Parameters

Request Body

Response

Success Response (200 OK)

Delete Policy

Endpoint

Request

Headers

Path Parameters

Response

Success Response (200 OK)

Notes and Warnings

Related Documentation