Appearance

IP Whitelisting ​

IP Whitelisting provides an additional layer of security by restricting API access to pre-approved IP addresses or CIDR ranges. This feature works seamlessly with API key and HMAC authentication.

Overview ​

IP Whitelisting operates as the first layer of FLUID's authentication stack, validating the source IP address before processing API keys or HMAC signatures.

Key Features ​

  • Optional Configuration: Enable/disable independently for each organization
  • IPv4 and IPv6 Support: Future-proof networking compatibility
  • CIDR Range Support: Whitelist entire IP ranges (e.g., 192.168.1.0/24)
  • Flexible Modes: Strict (whitelist-only) or Permissive
  • Expiring Entries: Time-limited IP access for temporary integrations
  • Comprehensive Logging: Full audit trail of access attempts

Authentication Stack ​

IP Whitelisting is Layer 1 in FLUID's security architecture:

Authentication Flow ​

  1. IP Validation: Check if request IP is authorized
  2. API Key Authentication: Verify Bearer token
  3. HMAC Verification: Validate signature (if enabled)
  4. Request Processing: Execute business logic

Configuration Modes ​

Only whitelisted IPs are allowed. All other IPs are blocked.

Use Cases:

  • Production environments
  • High-security requirements
  • Known, stable IP addresses

Example Response (blocked IP):

json
{
  "success": false,
  "error": {
    "code": 1451,
    "message": "IP address not authorized",
    "category": "security",
    "severity": "high"
  },
  "details": "IP address 203.0.113.50 is not authorized",
  "meta": {
    "timestamp": "2025-01-18T10:30:00Z",
    "request_id": "req_abc123",
    "blocked_ip": "203.0.113.50"
  }
}

Permissive Mode ​

All IPs are allowed except explicitly blacklisted ones.

Use Cases:

  • Development/testing
  • Dynamic IP environments
  • Gradual rollout

IP Whitelist Management ​

Enable IP Whitelisting ​

Contact FLUID support to enable IP whitelisting for your organization:

Email: support@fluidnetwork.africa
Subject: "Enable IP Whitelisting - [Your Organization]"

Provide:

  • Organization name and account ID
  • List of IP addresses or CIDR ranges to whitelist
  • Preferred mode (strict or permissive)
  • Expiration dates (if applicable)

FLUID support will configure your IP whitelist and confirm when it's active.

IP Address Formats ​

IPv4 Addresses ​

Single IP addresses or CIDR ranges:

# Single IP
203.0.113.10

# Class C network (256 addresses)
192.168.1.0/24

# Class B network (65,536 addresses)
172.16.0.0/16

# Custom range (128 addresses)
10.0.0.0/25

IPv6 Addresses ​

Full IPv6 support for future compatibility:

# Single IPv6
2001:0db8:85a3:0000:0000:8a2e:0370:7334

# IPv6 CIDR range
2001:0db8:85a3::/48

Use Cases ​

Static Office Network ​

Request to whitelist your office IP range for all API access:

Example Request to Support:

  • IP Range: 203.0.113.0/24
  • Description: Company HQ network
  • Expiration: None (permanent)

Multiple Data Centers ​

Request separate entries for each data center:

Example Request to Support:

  • IP: 203.0.113.10 - US East datacenter
  • IP: 198.51.100.20 - EU West datacenter
  • IP: 192.0.2.30 - Asia Pacific datacenter

Temporary Contractor Access ​

Request time-limited access for external developers:

Example Request to Support:

  • IP: 198.51.100.100
  • Description: Contractor - John Doe
  • Expiration: 30 days from activation

Dynamic IP with VPN ​

Request to whitelist your VPN's static exit IP:

Example Request to Support:

  • IP: 203.0.113.50
  • Description: Company VPN gateway
  • Expiration: None (permanent)

Testing Your Configuration ​

1. Verify Current IP ​

Check your current IP address:

bash
curl https://api.ipify.org

2. Test API Access ​

Make a test request to verify access:

bash
curl https://api.fluid-network.com/api/v1/payment-providers/banks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Implementation Notes:

Your application should test access by:

  1. Make a simple GET request to an endpoint like /banks to verify connectivity
  2. Check the HTTP status code:
    • 200 OK - Your IP is whitelisted and API key is valid
    • 403 Forbidden with error code 1451 - Your IP is blocked
    • 401 Unauthorized - API key issue (not IP-related)
  3. Parse the response and handle both success and error cases appropriately
  4. Log the result for debugging (include your current IP address for troubleshooting)

Expected Response (IP allowed):

json
{
  "success": true,
  "data": [
    {
      "identifier": "EXB",
      "name": "Example Bank Ghana",
      "country": "GH",
      "currency": "GHS",
      "active": true
    }
  ]
}

Expected Response (IP blocked):

json
{
  "success": false,
  "error": {
    "code": 1451,
    "message": "IP address not authorized",
    "category": "security",
    "severity": "high"
  },
  "details": "IP address 203.0.113.99 is not authorized"
}

Error Codes ​

CodeMessageDescription
1451IP address not authorizedRequest from non-whitelisted IP
1452IP address validation failedMalformed or invalid IP address
1453Rate limit exceeded for IP addressToo many requests from this IP

Best Practices ​

1. Gradual Rollout ​

Start with permissive mode, then switch to strict:

  1. Deploy with permissive mode enabled
  2. Monitor access logs for legitimate IPs
  3. Add IPs to whitelist based on logs
  4. Switch to strict mode after verification
  5. Monitor for blocked IPs and add as needed

2. Redundancy Planning ​

Plan for IP changes:

  • Add new IPs before removing old ones
  • Set expiration dates for temporary IPs
  • Document all IP addresses and their purposes
  • Maintain an emergency contact for urgent changes

3. Security Considerations ​

  • Use CIDR ranges for office networks
  • Avoid overly broad ranges (e.g., /8)
  • Set expiration dates for contractor access
  • Review whitelist entries quarterly
  • Combine with HMAC for maximum security

4. Monitoring ​

Request access logs from FLUID support to monitor:

  • Blocked IP attempts
  • Geographic distribution of requests
  • Unusual access patterns
  • Expiring whitelist entries

Troubleshooting ​

Issue: Requests Blocked Despite Whitelisting ​

Possible Causes:

  • IP address changed (dynamic IP)
  • Request going through proxy/load balancer
  • CIDR range doesn't include your IP
  • Whitelist entry expired

Solutions:

  1. Verify your current IP: curl https://api.ipify.org
  2. Check if using proxy/VPN with different exit IP
  3. Contact support to verify whitelist configuration
  4. Add broader CIDR range if IPs change within subnet

Issue: Intermittent Access ​

Possible Causes:

  • Multiple outbound IPs (load balancing)
  • Failover systems with different IPs
  • VPN with multiple exit points

Solutions:

  • Identify all outbound IPs
  • Add all IPs to whitelist
  • Use CIDR range to cover all possible IPs

Issue: IPv6 Requests Blocked ​

Possible Causes:

  • Only IPv4 addresses whitelisted
  • Server using IPv6 but whitelist has IPv4

Solutions:

  • Add both IPv4 and IPv6 addresses
  • Check which IP version your server uses: curl -6 https://api.ipify.org

Migration Guide ​

Step 1: Audit Current IPs ​

Identify all IPs that need access:

bash
# Find your production server IPs
curl https://api.ipify.org

# Check all servers/environments
ssh prod-server-1 "curl https://api.ipify.org"
ssh prod-server-2 "curl https://api.ipify.org"

Step 2: Request Enablement ​

Email FLUID support with:

  • Complete list of IPs/CIDR ranges
  • Description of each IP (server name, purpose)
  • Preferred mode (start with permissive)

Step 3: Testing ​

Test from each whitelisted IP:

bash
# From each server
curl https://api.fluid-network.com/api/v1/payment-providers/banks \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 4: Monitor ​

Monitor for blocked requests for 7-14 days before switching to strict mode.

Step 5: Enable Strict Mode ​

Once confident all legitimate IPs are whitelisted, request strict mode activation.

Combining with Other Security Layers ​

IP Whitelisting works best when combined with other security measures:

IP Whitelisting + API Keys ​

Basic security setup (minimum recommended):

Layer 1: IP Whitelisting (restrict source)
Layer 2: API Key (authenticate organization)

IP Whitelisting + API Keys + HMAC ​

Maximum security setup (recommended for production):

Layer 1: IP Whitelisting (restrict source)
Layer 2: API Key (authenticate organization)
Layer 3: HMAC Signature (verify integrity)

See HMAC Authentication for implementation details.

Next Steps ​

Support ​

Questions about IP Whitelisting?

  • Email: support@fluidnetwork.africa
  • Subject: "IP Whitelisting Support - [Your Organization]"
  • Include: Your organization name, current issue, and current IP address

Copyright © 2025 FLUID Network