Overview
What is its Purpose?
- Increase Access Security: Ensures that services provided through API Gateway are accessed only from trusted IP addresses.
- Block Unauthorized Access: Minimizes security vulnerabilities by automatically rejecting requests from sources not on the whitelist.
- Apply Geographic Restrictions: Creates geography-based security policies by accepting or blocking requests from specific countries and cities.
- Centralized IP Management: Makes the same IP sets reusable in different policies using IP groups.
- Dynamic IP Management: Provides the ability to dynamically change IP list at runtime with Variable mechanism.
Working Principle
- Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the client’s source IP address is identified.
- Policy Check: If the IP Whitelist policy is active, the system checks in the following order:
- Is a Condition defined? If so, is the condition met?
- Is the policy active (active=true)?
- Is a Variable being used or is Apinizer default?
- IP Verification: It is checked whether the client IP address matches one of these sources:
- Manually defined IP list (ipList)
- IPs in IP Groups (ipGroupIdList)
- Geolocation settings (geoLocationDataList)
- Decision Making:
- Match Found: Request is forwarded to the next policy step or backend service.
- No Match: Request is rejected and customized error message is returned (default: 403 Forbidden).
- Error Handling: Customizable HTTP status code and error message are returned for requests that do not comply with the policy rule.
Features and Capabilities
Basic Features
- Manual IP List Management: Define IP ranges with IPv4 addresses and CIDR notation (e.g., 192.168.1.0/24). Each IP address can be added separated by commas and real-time verification is performed.
- IP Group Integration: Add predefined IP groups to the policy. Ability to select and manage multiple IP groups simultaneously. IP groups are updated centrally and automatically reflected in the policy.
- Global and Local Policy Support: Can be defined globally and used in multiple API Proxies or configured as a local policy for a specific API Proxy.
- Active/Passive Status Control: Easily change the active or passive status of the policy (active/passive toggle). In passive mode, the policy is not applied but its configuration is preserved.
- Condition-Based Application: Determine when the policy will be applied by creating complex conditions with Query Builder (e.g., only for specific endpoints or header values).
Advanced Features
- Geolocation (Geographic Location) Support: IP control by country and city through Geolocation service integration. Accept/block requests from entire country or specific cities. Ability to define multiple country and city combinations.
- Variable Mechanism: Dynamically change IP list at runtime using Variable. Get IP list from external systems (database, cache, API). Options to merge or override with Variable.
- Error Message Customization: Customize HTTP status code (default: 403). Define custom JSON or XML error messages. Configure different messages for different error scenarios.
- Export/Import Feature: Export policy configuration as a ZIP file. Import to different environments (Development, Test, Production). Version control and backup capability.
- Policy Group and Proxy Group Support: Manage multiple policies within Policy Group. Bulk policy assignment to Proxy Groups. Centralized update and deploy operations.
- Deploy and Versioning: Deploy policy changes to live environment. See which API Proxies use it (Policy Usage). Proxy Group and Policy Group usage reports.
Usage Scenarios
| Scenario | Status | Solution (Policy Application) | Expected Behavior / Result |
|---|---|---|---|
| Corporate Network Access | Only access from corporate network (192.168.0.0/16) should be allowed to APIs | Add 192.168.0.0/16 CIDR block to IP list. Assign policy to relevant API Proxy locally or globally. | Only requests from 192.168.x.x network are accepted. Other IPs return 403 error. |
| Third-Party Integration | Allow requests from specific partner company’s fixed IPs (203.0.113.10, 203.0.113.11) | Add 203.0.113.10 and 203.0.113.11 addresses to IP list. Create “Partner IP Group” and reuse if needed. | Only requests from partner IPs are accepted. Integrations work securely. |
| Geographic Restriction | Only accept requests from Turkey (TR) | Enable Geolocation settings. Select Turkey from “Select Country” list and add to policy. | If client IP does not belong to Turkey geography, 403 error is returned. TR IPs are accepted. |
| City-Based Access | Accept requests only from Istanbul and Ankara cities | Select Turkey from Geolocation section. Select Istanbul and Ankara from city list. Click “Add” button. | Only IPs from Istanbul and Ankara cities are accepted. Other cities are rejected. |
| Development/Test Environment | Allow access only from QA team IPs in test environment | Create an IP Group named “QA Team IPs”. Add this group to policy. Make global policy specific to test environment. | QA team can access test APIs. Different policy is applied in production environment. |
| Dynamic IP Management | IP list changes regularly (daily updates) | Use Variable mechanism. Feed Variable from external system (database, API). Close “Use Apinizer Default” in policy and select variable. | Current IP list is retrieved from variable when each request arrives. Manual update not required. |
| Emergency Access | Always accept requests from a specific critical IP | Add critical IP to manual IP list. Add emergency header check in condition section (optional). | Critical IP always has access. Policy can be bypassed in emergencies. |
Configuring Policy Parameters
In this step, users can create a new policy or configure existing policy parameters to define access rules. The defined parameters directly affect how the policy works (e.g., which IPs will be allowed, geographical restrictions, conditional activations, etc.). This allows the policy to be customized according to organization-specific requirements while being centrally manageable.Creating a New Allowed IP List Policy
Configuration Steps
| Step | Description / Operation |
|---|---|
| Step 1: Go to Creation Page | - Go to Development → Global Settings → Global Policies → Allowed IP List from the left menu. - Click the [+ Create] button at the top right. |
| Step 2: Enter Basic Information | Policy Status: Shows Active/Passive status. New policies are active by default. Name (Required): Example: Production_IP_Whitelist- Enter a unique name, does not start with space. - System automatically checks: Green checkmark: available Red X: existing name. Description: Example: “Allows requests only from corporate internal and partner systems for Prod environment.” - Max. 1000 characters. - Explain the purpose of the policy. |
| Step 3: IP List Configuration | Use Apinizer Default: ☑️ Uses default IP detection mechanism. You need to define your own variable (Variable). Adding IP: - Single IP: 192.168.1.100 → Added with Enter or ✓.- CIDR: 192.0.2.0/24 → Covers 192.0.2.0–192.0.2.255 range./24 → 256 IPs, /30 → 4 IPs, /32 → single IP. Deleting IP: Click on IP tag or ✕ icon. Characters (’*’ and ’-’) can be used to specify IP ranges. Examples: - 10.0.0.1 → Single IP- 192.168.1.0/24 → 256 IPs- 172.16.0.0/12 → 1,048,576 IPs- 203.0.113.0/30 → 4 IPs (.0-.3)- 10.3.10.* value specifies IPs between ‘10.3.10.0’ and ‘10.3.10.255’.- 10.3.10.4-18 value expresses IPs between ‘10.3.10.4’ and ‘10.3.10.18’ (4 and 18 included).Enter key must be pressed after adding IP. |
| Step 4: IP Groups Usage (Optional) | - Click “Click to add IP Groups” button. - Existing IP groups appear on left, selected ones on right. Adding: - Select group from left list → [Select]. - Moves to right side. - A group can be used in multiple policies. Removing: - Click 🗑️ icon in right list → returns to left list. Advantage: - Manage IP lists centrally. - Single update reflects to all policies. - Ideal for partner access. |
| Step 5: Geographic Location Filter (Optional) | - Select country from Country dropdown (example: Turkey). - City dropdown becomes active when country is selected (example: Istanbul, Ankara, Izmir). - Added to table with [+ Add]. - Rows can be deleted individually with 🗑️ or in bulk with top 🗑️. Example Scenarios: - Turkey only: Country: Turkey, City: — - Turkey major cities: Istanbul, Ankara, Izmir, Bursa - Multiple countries: Turkey (all), Germany (Berlin, Munich), USA (all) |
| Step 6: Define Condition (Optional) | - Go to Condition tab. - Conditions determine when the policy will be active. Examples: • Environment-based: Header = X-Environment, Operator = Equals, Value = production • API Key-based: Header = X-API-Key, Starts With = PROD- • Endpoint-based: Path = /api/admin/* If no condition is defined, policy is always active. |
| Step 7: Customize Error Message (Optional) | - Go to Error Message Customization tab - Customize the message to be returned when access is denied. Default: { "statusCode": 403, "message": "Access denied: IP not whitelisted" }Custom: { "statusCode": 403, "errorCode": "ACCESS_DENIED", "message": "You do not have permission to access this API.", "details": "Your IP address is not on the allowed list. Please contact [email protected] for access." } |
| Step 8: Save | - Click the [Save] button at the top right. Checklist: - Unique name - Required fields filled - At least one IP or group exists Result: - Policy is added to the list. - Can be connected to APIs. - If global policy, automatically applied. |
Deleting the Policy
For deletion steps of this policy and operations to be applied when in use, you can refer to the Remove Policy from Flow section on the Policy Management page.Exporting/Importing the Policy
For export (Export) and import (Import) steps of this policy, you can refer to the Export/Import page.Connecting the Policy to API
For the process of how this policy will be connected to APIs, you can refer to the Connect Policy to API section on the Policy Management page.Advanced Features
| Feature | Description and Steps |
|---|---|
| Dynamic IP Management with Variable | - First create a Variable (from Variables menu). Variable type should be “String List” or “JSON”. - Feed Variable from external system (Database, Redis, API, etc.). - Close “Use Apinizer Default” toggle in policy creation/editing page. - Select relevant variable from “Variable” section. - Save. Now IP list is read from variable when each request arrives. - Does not require manual update, real-time IP list management. |
| Centralized Management with IP Group | - Create a new IP Group from IP Group menu (e.g., “Partner IPs”). - Add IPs to IP group (same logic, IPv4 and CIDR supported). - Use this group in different IP Whitelist policies. - Update IP Group (add/remove new IP). - Changes automatically reflect to all policies using this group. Advantage: Using one IP set in multiple policies, updating from single point. |
| Country-Based Blocking with Geolocation | Prerequisite: Geolocation service must be activated from Geolocation Settings. - Open country dropdown in “Geolocation” section on policy page. - Select desired country (e.g., Germany). - Click [ Add ] button without selecting city (applies to entire country). - You can add multiple countries. Advantage: Geographic location-based access control without needing IP information |
| City-Based Blocking with Geolocation | - After selecting country, “City” dropdown becomes active. - Select one or multiple cities (supports multi-select). - Click [ Add ] button. - Added cities appear in table format. Example: If “Turkey - Istanbul” and “Turkey - Ankara” are selected, only requests from these two cities are accepted. Note: Accuracy of city data depends on Geolocation provider. |
| Conditional IP Control with Condition | - Go to “Condition” tab on policy editing page. - Create condition in Query Builder (e.g., path='/admin' OR header.X-Admin-Request='true').- IP control is performed when condition is met, policy is skipped if not met. - Save. - Special IP restriction for admin endpoints, no IP control for public APIs. Advantage: Different policy behaviors for different endpoints in the same API Proxy. |
| Error Message Customization | - Go to “Error Message Customization” tab. - Select error type (e.g., “IP Not Whitelisted”). - Change HTTP Status Code (e.g., 401 instead of 403). - Enter custom JSON message: { "error": "Access Denied", "message": "Your IP address is not whitelisted", "code": "IP_NOT_ALLOWED" }- Add language-based messages (TR, EN). - Save. Advantage: More meaningful error messages to users, custom error tracking. |
| Policy Transfer with Export/Import | Export: - Select [ Export ] from ”…” menu in policy list. - ZIP file is downloaded (format: DD-MMM-YYYY-policy-[name]-export.zip).Import: - Click [ Import ] button on list page. - Select exported ZIP file. - Configure import settings (override, new name, etc.). - Complete import process. Advantage: Policy transfer between Development → Test → Production environments, backup. |
| Bulk Management with Policy Group | - Create a new group from “Policy Group” menu. - Add multiple policies including IP Whitelist policy to group. - Assign Policy Group to one or multiple API Proxies. - All policies in group are applied in bulk. Advantage: Managing multiple policies as package, bulk deploy. |
Tips and Best Practices
Things to Do and Best Practices
| Category | Description / Recommendations |
|---|---|
| IP Format and Definition | Bad: 192.168.1 (incomplete format)Good: 192.168.1.100 (full IPv4 address)Best: 192.168.1.0/24 (IP range with CIDR, 254 addresses with single definition) |
| IP Group Usage | Bad: Manually adding same IP list in each policy Good: Defining IP group once Best: Categorizing and grouping relevant IPs (e.g., “Partner IPs”, “Office IPs”, “QA Team IPs”) |
| Global vs Local Policy Selection | Bad: Creating separate local IP Whitelist policy for each API Proxy Good: Using global policy as common security policy Best: Using global for general rules, local policy for special cases |
| Geolocation Usage | Bad: Manually adding all country IP blocks Good: Activating Geolocation service Best: Providing precise control using country and city combinations |
| Dynamic Management with Variable | Bad: Updating policy on every IP change Good: Getting IP list from external system using Variable Best: Caching Variable in Redis/Database for high performance |
| Error Message Customization | Bad: Using default 403 error Good: Making detailed explanation with custom JSON message Best: Different messages for different error scenarios, adding log ID |
| Policy Naming | Bad: Ambiguous names like policy1, ipwhiteGood: Descriptive names like IP_White_List_ProductionBest: [ENV]_[Purpose]_IP_White format (e.g., PROD_Partner_API_IP_White) |
| Condition Usage | Bad: Applying same IP restriction to all endpoints Good: Separating public and private endpoints Best: Special IP control for /admin/* paths with Condition, no IP control for /public/* paths |
Security Best Practices
| Security Area | Description / Warnings |
|---|---|
| Least Privilege Principle | Critical: Add only truly necessary IPs to IP Whitelist. Absolutely avoid using wide CIDR blocks (e.g., 0.0.0.0/0).Recommendation: Use /32 (single IP) or at most /24 (256 IPs). |
| IP Spoofing and Proxy Security | Warning: If there is a Load Balancer or Reverse Proxy in front of API Gateway, correctly configure X-Forwarded-For or X-Real-IP headers to get real client IP.Risk: Risk of bypassing whitelist with IP spoofing. |
| Geolocation Reliability | Note: Geolocation services are not 100% accurate. Can be bypassed with VPN and Proxy usage. Recommendation: Use Geolocation not alone, but together with other security layers (JWT, API Key, etc.). |
| Variable Security | Security Risk: If Variable content comes from external system, ensure security of that system. Recommendation: Apply authentication, encryption, and access control for Variable datasource. |
| Error Message Information Leakage | Caution: Do not provide information about system architecture or internal IPs in error messages. Bad: “Your IP 203.0.113.5 is not in whitelist. Allowed range: 192.168.1.0/24” Good: “Access denied. Your IP address is not authorized.” |
| Regular Update and Review | Best Practice: Regularly review IP Whitelist (e.g., monthly). Action: Remove unused, old partner IPs. Update changed IPs. Check audit logs. |
| Multi-Factor Security | Recommendation: Do not use IP Whitelist as single security layer. Best Practice: Use combination of IP control + API Key/JWT + Rate Limiting. |
| Production Environment Isolation | Critical: Create separate global policy for Production environment. Never add Test/Development environment IPs to production policy. Recommendation: Use environment-based Policy Group. |
Things to Avoid
| Category | Description / Warnings |
|---|---|
| Using Wide CIDR Blocks | Why to avoid: Wide blocks like 10.0.0.0/8 can cover millions of IPs and increase security risk.Alternative: Use specific subnets (e.g., 10.10.50.0/24). Add needed IPs one by one or with small CIDR blocks. |
| Not Defining Fallback When Using Variable | Why to avoid: All requests may be blocked if Variable service is down or returns empty. Alternative: Use Variable + Manual IP list together. Add fallback configuration to manual list if Variable cannot be read. Set up monitoring and alerting. |
| Leaving Policy in Passive State | Why to avoid: Passive policy is not applied to traffic, security vulnerability may occur if forgotten. Alternative: Make passive temporarily for short time to test. Activate or delete after test is complete. |
| Providing IP Information in Error Message | Why to avoid: Showing client’s or allowed IPs in error message gives information to attackers. Alternative: Use general error messages: “Access denied” or “Unauthorized”. Keep detailed logs only on server side. |
| Complicating Management with Local Policy | Why to avoid: Creating separate local IP Whitelist policy for each API Proxy complicates management and creates inconsistency in IP updates. Alternative: Use global policy. Create local policy only for API Proxies with truly different IP requirements. |
| Over-Reliance on Geolocation | Why to avoid: Geographic location can be bypassed with VPN, Tor, Proxy usage. Not sufficient for sensitive operations. Alternative: Use Geolocation as additional security layer. Apply IP + Authentication + MFA combination for critical operations. |
| Not Deploying Policy Updates | Why to avoid: Changes made in global policy do not reflect to live environment without deploy. Alternative: Use Deploy button after policy is updated. Integrate deploy process into CI/CD pipeline. |
| Transitioning to Production Without Testing | Why to avoid: Wrong IP configuration may cause blocking of all users. Alternative: Validate policy in test environment. Deploy first in passive mode, check logs. Then activate. Prepare rollback plan. |
Performance Tips
| Criterion | Recommendation / Impact |
|---|---|
| IP Group Size | Recommendation: Limit IP groups to maximum 100-200 IPs. Create multiple groups if more IPs are needed. Impact: Entire IP list is checked on each request. Very large lists reduce performance (O(n) comparison for each IP). |
| Preferring CIDR Blocks | Recommendation: Use CIDR notation for IP ranges as much as possible. Performance Difference: Using 192.168.1.0/24 (1 entry) instead of 192.168.1.1, 192.168.1.2, ..., 192.168.1.254 (254 entries) is 100x faster. |
| Variable Cache Strategy | Recommendation: Use cache mechanism in Variable datasource (Redis, Memcached). Impact: Reading from cache instead of database query on each request reduces millisecond delay to microsecond. TTL can be 5-10 minutes. |
| Geolocation Performance | Note: Geolocation lookup occurs on each request and creates additional delay (average 1-5ms). Recommendation: Prefer using fixed IP list instead of geolocation in high-traffic APIs. Cache geolocation results (IP → Country/City mapping). |
| Condition Complexity | Recommendation: Write simple and optimized conditions. Avoid unnecessarily complex regex or nested conditions. Impact: Simple condition ( path='/' AND method='GET') < 0.1ms. Complex regex condition > 1-2ms. |
| Policy Ordering | Best Practice: Run IP Whitelist policy first within Policy Group. Logic: If requests from unauthorized IPs are blocked at early stage, other policies (Rate Limiting, JWT, etc.) do not run unnecessarily. |
| Log Level Setting | Production: Keep log level at ERROR or WARN. Development: You can use DEBUG or TRACE. Impact: Excessive logging (logging IP check on each request) can cause disk I/O and performance issues. |
| Deleting Inactive Policies | Recommendation: Regularly delete unused or passive policies. Impact: Keeps database and in-memory policy registry small, reduces policy lookup time. |
Frequently Asked Questions (FAQ)
| Category | Question | Answer |
|---|---|---|
| General | How many IPs does IP Whitelist policy support? | There is no technical limit but 500-1000 IPs are recommended for performance. Use IP groups and CIDR blocks for more IPs. External cache (Hazelcast) usage with Variable is recommended for very large lists. |
| General | Are IPv6 addresses supported? | IPv4 and CIDR blocks are supported in current implementation. IPv6 support is on product roadmap. As temporary solution, you can do routing at reverse proxy level for IPv6 traffic. |
| General | Should API Proxy be deployed even if I make policy passive? | Yes. Every change made in global policies (including active/passive) must be deployed. In local policies, the API Proxy itself must be deployed. |
| Technical | How is IP retrieved from X-Forwarded-For header? | API Gateway automatically checks X-Forwarded-For, X-Real-IP headers. You must activate “Use Forwarded IP” option from Gateway settings. If header does not exist, direct socket IP is used. |
| Technical | How should IP list be formatted with Variable? | If Variable type is “String List”:["192.168.1.1", "192.168.1.2", "10.0.0.0/8"]If Variable type is “JSON”: {"ipList": ["192.168.1.1", "192.168.1.2"], "allowAll": false}Variable is read when each request arrives or retrieved from cache. |
| Technical | How is CIDR block calculated? | CIDR notation: IP_ADDRESS/PREFIX_LENGTHExamples: - 192.168.1.0/32 = Single IP (192.168.1.0)- 192.168.1.0/24 = 256 IPs (192.168.1.0 - 192.168.1.255)- 10.0.0.0/8 = 16,777,216 IPs (10.0.0.0 - 10.255.255.255)You can use online CIDR calculators. |
| Technical | Which HTTP headers are added when policy is applied? | No header is added when policy is successful. Custom error message is returned when failed (IP rejected). You can add custom headers like X-Apinizer-Policy-Status: REJECTED for debugging. |
| Usage | If I use both IP list and Geolocation, is the logic AND or OR? | OR logic works. That is, client IP is accepted if it matches any of these sources: - Manual IP list - IPs in IP Groups - Geolocation country/city rules - IPs from Variable Rejected if it matches none. |
| Usage | I updated global policy but it didn’t reflect on API, why? | Global policy changes must be deployed. Process steps: - Save the policy. - Click “Deploy” button on policy detail page. - Select environments to deploy (DEV, TEST, PROD). - Confirm deploy process. - Changes reflect to live within 1-2 minutes after deploy. |
| Usage | What happens to policy if I delete IP Group? | Caution: If IP Group is deleted, policies using this group become invalid (⚠️ validation warning is shown). Deleted group ID remains in policy ipGroupIdList but IPs do not match. Recommendation: Check which policies use it before deleting IP Group. Update policies first if needed. |
| Usage | How is Geolocation service activated? | - Go to “Geolocation Settings” page from Admin menu. - Select Geolocation provider (e.g., MaxMind GeoIP2). - Enter API Key or license information. - Test connection with “Test Connection”. - Open “Enable Geolocation” toggle and save. - Geolocation database must be updated regularly (monthly). |
| Usage | Can I use both global and local IP Whitelist policy in one API Proxy? | Technically yes, but not recommended. If both policies are active, AND logic works (must match both lists). Can lead to complex management and unexpected blockings. Best Practice: Use global policy. If specific case exists, localize global policy and customize. |
| Troubleshooting | I’m getting “Invalid IP address format” error, why? | IP address format is incorrect. Valid formats: ✅ 192.168.1.100 (IPv4)✅ 10.0.0.0/8 (CIDR)❌ 192.168.1 (missing octet)❌ 192.168.1.300 (300 > 255, invalid)❌ 192.168.1.0/33 (CIDR prefix must be between 0-32)Edit your IP according to these formats. |
| Troubleshooting | IP I added to Whitelist still gets 403, what should I do? | Troubleshooting steps: - Check if policy is active (active=true). - Check if global policy is deployed. - See client’s real IP in API Gateway logs (X-Forwarded-For if behind Load Balancer). - Is Condition defined? Check if condition is met. - Is IP in correct format? Is CIDR block calculated correctly? - If Variable is used, check Variable content. - Clear cache (reload policy cache). If problem persists, send log files to support team. |
| Troubleshooting | Geolocation control is not working, what should I do? | Checklist: - Is service active in Geolocation Settings? - Is Geolocation database current? (Check last update date) - Is client IP a public IP? (Geolocation does not work for private IPs: 192.168.x.x, 10.x.x.x) - VPN or Proxy may be used (hides real location). - Check geolocation lookup result in API Gateway logs (which country/city was detected). - Geolocation provider’s API limit may have been reached. |