Allowed IP List Policy

General Information

Policy Type

policy-white-ip

UI Documentation

📖 For detailed information: [UI Documentation Link - Link will be added here]

Description

White IP policy allows requests only from specified IP addresses or IP ranges. Requests from IPs not in the whitelist are rejected before reaching the backend. This policy is useful for restricting API access to specific networks, offices, or trusted IPs.

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)

{
  "success": true,
  "resultList": [
    {
      "apiProxy": {
        "name": "MyAPI",
        "requestPolicyList": [
          {
            "type": "policy-white-ip",
            "name": "white-ip-policy",
            "description": "Allow only trusted IPs",
            "active": true,
            "targetVariableForIP": null,
            "ipList": [
              "192.168.1.0/24",
              "10.0.0.0/8",
              "203.0.113.100"
            ]
          }
        ],
        "responsePolicyList": [],
        "errorPolicyList": []
      }
    }
  ],
  "resultCount": 1
}

Note: In list operations, ipList may be omitted for brevity.

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

Request Body

Full JSON Body Example
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-white-ip",
    "description": "Allow only trusted IP addresses",
    "active": true,
    "targetVariableForIP": null,
    "ipList": [
      "192.168.1.0/24",
      "10.0.0.0/8",
      "203.0.113.100",
      "2001:db8::/32"
    ]
  }
}
Request Body Fields
operationMetadata
Field Type Required Default Description
targetScope string Yes - Policy scope: ALL or ENDPOINT
targetEndpoint string No* - Endpoint path (required if targetScope=ENDPOINT)
targetEndpointHTTPMethod string No* - HTTP method (required if targetScope=ENDPOINT)
targetPipeline string Yes - Pipeline: REQUEST, RESPONSE, or ERROR
deploy boolean No true Whether to deploy after adding policy
deployTargetEnvironmentNameList array No [] List of environment names to deploy to
order integer No null Policy execution order (starts from 1)

Enum: targetScope

  • ALL - Policy applies to all endpoints
  • ENDPOINT - Policy applies only to specified endpoint

Enum: targetPipeline

  • REQUEST - Executes in request pipeline
  • RESPONSE - Executes in response pipeline
  • ERROR - Executes in error pipeline

Enum: targetEndpointHTTPMethod

  • GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
policy
Field Type Required Default Description
type string Yes - Policy type: policy-white-ip
description string No - Policy description
active boolean No true Whether policy is active
targetVariableForIP object No null Variable to extract IP address (null = use Apinizer default)
ipList array Yes - List of IP addresses or CIDR ranges to allow

IP Address Formats

  • Single IP: 192.168.1.100 (IPv4) or 2001:db8::1 (IPv6)
  • CIDR Range: 10.0.0.0/8 (IPv4) or 2001:db8::/32 (IPv6)
  • Multiple entries: Array of IPs and CIDR ranges

Note

  • ipList must contain at least one IP address or CIDR range.
  • When targetVariableForIP is null, Apinizer uses default IP detection (from X-Forwarded-For header or direct connection).
  • Only IPs in the whitelist are allowed. All other IPs are blocked.
targetVariableForIP (Optional)
Field Type Required Description
type string Yes Variable type: HEADER, PARAMETER, BODY, CONTEXT, SCRIPT
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)

type

  • HEADER - Extract from HTTP header (e.g., X-Forwarded-For, X-Real-IP)
  • PARAMETER - Extract from query/path parameter
  • BODY - Extract from request body
  • CONTEXT - Extract from context (e.g., CLIENT_IP)
  • SCRIPT - Extract using script

contextValue

  • CLIENT_IP - Client IP address (recommended for IP filtering)
  • REQUEST_URI - Request URI
  • REQUEST_METHOD - HTTP method
  • USER_AGENT - User agent string

Default IP Detection

When targetVariableForIP is null, Apinizer automatically detects the client IP from:

  1. X-Forwarded-For header (if present)
  2. Direct connection IP address

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/white-ip-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-white-ip",
      "description": "Allow only trusted IP addresses",
      "active": true,
      "ipList": [
        "192.168.1.0/24",
        "10.0.0.0/8"
      ]
    }
  }'

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

Request Body

Full JSON Body Example
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-white-ip",
    "description": "Updated white IP list",
    "active": true,
    "targetVariableForIP": {
      "type": "HEADER",
      "headerName": "X-Forwarded-For"
    },
    "ipList": [
      "192.168.1.0/24",
      "192.168.2.0/24",
      "10.0.0.0/8",
      "203.0.113.100",
      "2001:db8::/32"
    ]
  }
}

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

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

cURL Example

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/white-ip-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-white-ip",
      "description": "Updated white IP list",
      "active": true,
      "ipList": [
        "192.168.1.0/24",
        "10.0.0.0/8"
      ]
    }
  }'

Delete Policy

Endpoint

DELETE /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

Request Body

Full JSON Body Example
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": false
  }
}
Request Body Fields
operationMetadata
Field Type Required Description  
targetScope string Yes Policy scope: ALL or ENDPOINT  
targetPipeline string Yes Pipeline: REQUEST, RESPONSE, or ERROR  
deploy boolean No false Whether to deploy after deletion

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": []
  }
}

cURL Example

curl -X DELETE \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/white-ip-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": false
    }
  }'

Notes and Warnings

  • IP List: Must contain at least one IP address or CIDR range
  • IP Formats:
    • Single IP: 192.168.1.100 (IPv4) or 2001:db8::1 (IPv6)
    • CIDR Range: 10.0.0.0/8 (IPv4) or 2001:db8::/32 (IPv6)
  • Whitelist Behavior: Only IPs in the whitelist are allowed. All other IPs are blocked.
  • IP Detection:
    • When targetVariableForIP is null, Apinizer uses default IP detection
    • Default detection checks X-Forwarded-For header and direct connection IP
  • Custom IP Extraction: Use targetVariableForIP to extract IP from custom headers or parameters
  • CIDR Notation: CIDR ranges allow all IPs within the specified range
  • IPv6 Support: Both IPv4 and IPv6 addresses are supported
  • Security: Use whitelist for maximum security - only explicitly allowed IPs can access the API
  • Performance: IP checking is fast, but large IP lists may impact performance
  • Order: This policy should typically be executed early in the request pipeline (low order number)
  • Deployment: Policy changes require deployment to take effect. Set deploy: true or deploy manually.