Egress IP Routing & VPN

Many APIs require whitelisting specific IP addresses. KnoxCall supports routing requests through dedicated egress servers with static IPs—either managed by KnoxCall or through your own VPN infrastructure.

The Problem

Dynamic IPs:

Your server: 198.51.100.50
   ↓
KnoxCall proxy: 203.0.113.100 (changes)
   ↓
Partner API: ❌ Rejects (IP not whitelisted)

APIs requiring IP whitelisting:

Banking and financial APIs (Open Banking, Plaid)
Government services (tax, compliance)
Enterprise B2B integrations
Payment processors (some configurations)
Internal corporate APIs

The Solution

Static egress IP:

Your server: 198.51.100.50 (any IP)
   ↓
KnoxCall proxy → Data plane node: 203.0.113.200 (fixed)
   ↓
Partner API: ✅ Accepts (203.0.113.200 is whitelisted)

Benefits:

✅ Single static IP to whitelist
✅ Works from any source (dev, staging, prod)
✅ Automatic failover if egress server down
✅ Choose geographic region
✅ Multiple egress IPs per tenant (if needed)

Types of Egress Routing

KnoxCall supports two deployment models:

1. Managed Egress Servers (Recommended)

What it is:

KnoxCall provisions and manages egress servers for you
Static IP provisioned in your chosen region
Automatic health monitoring and failover
No infrastructure management required

When to use:

You need a quick, turnkey solution
You want KnoxCall to handle operations
You don’t have existing VPN infrastructure

Regions available:

🇺🇸 US East (New York)
🇺🇸 US West (San Francisco)
🇪🇺 EU West (London)
🇪🇺 EU Central (Frankfurt)
🇦🇺 APAC (Sydney)
🇸🇬 APAC (Singapore)

Pricing:

Included in Business and Enterprise plans
$29/month per additional egress server (if you need multiple regions)

2. Self-Hosted VPN Integration

What it is:

Connect KnoxCall to your existing VPN infrastructure
Routes traffic through your VPN gateway
You manage the VPN server, KnoxCall just uses it

When to use:

You have existing VPN infrastructure
Compliance requires self-hosted networking
You need specific routing or firewall rules
You want full control over egress traffic

Supported VPN types:

WireGuard
OpenVPN
Custom proxy servers (SOCKS5, HTTP forward proxy)

Pricing:

Included in Enterprise plan
Contact sales for availability on lower tiers

Setting Up Managed Egress

Step 1: Request Egress Server

Navigate to Infrastructure → Egress Servers
Click Create Egress Server
Configure:

Name: US East Egress
Region: us-east-1 (New York)
Purpose: Banking APIs

Click Provision

Step 2: Wait for Provisioning

KnoxCall automatically:

Creates a DigitalOcean Droplet in your region
Configures forward proxy software
Assigns a static IP (reserved IP)
Sets up health checks
Registers in data plane registry

Typical provisioning time: 2-3 minutes

Step 3: Note Your Static IP

After provisioning completes:

Egress Server: US East Egress
├─ Status: ✅ Active
├─ Region: us-east-1 (New York, USA)
├─ Egress IP: 203.0.113.200
├─ Last seen: 12 seconds ago
└─ Routes using: 0

Share this IP with your API provider for whitelisting.

Step 4: Assign to Routes

Configure which routes use the egress server: Option A: Per-environment (recommended)

Go to route detail page
Select environment (e.g., “production”)
Scroll to Advanced → Egress Routing
Select egress server: “US East Egress”
Save

Option B: Via API

PUT /admin/routes/{route_id}/environments/{environment}

{
  "data_plane_node_id": "dpn_abc123"
}

Step 5: Test & Verify

Make a test request through your route:

curl https://yourapp.com/api/v1/proxy/your-route \
  -H "Authorization: Bearer your-token"

Check the API provider’s logs to confirm they see requests from 203.0.113.200.

Setting Up Self-Hosted VPN

Prerequisites

VPN server (WireGuard or OpenVPN)
VPN configuration file or credentials
Network access from KnoxCall servers

Step 1: Prepare VPN Configuration

WireGuard example:

[Interface]
PrivateKey = <your-private-key>
Address = 10.0.0.2/24

[Peer]
PublicKey = <server-public-key>
Endpoint = vpn.yourcompany.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

OpenVPN example:

client
dev tun
proto udp
remote vpn.yourcompany.com 1194
ca ca.crt
cert client.crt
key client.key

Step 2: Register VPN in KnoxCall

Navigate to Infrastructure → Data Plane Nodes
Click Add Self-Hosted VPN
Configure:

Name: Corporate VPN
Type: wireguard
Configuration: (paste WireGuard config)
Egress IP: 203.0.113.200 (your VPN's egress IP)
Health Check URL: https://vpn-health.yourcompany.com/ping (optional)

Click Save

Step 3: Test Connection

KnoxCall will:

Establish VPN tunnel
Perform health check (if configured)
Report connectivity status

VPN Node: Corporate VPN
├─ Status: ✅ Connected
├─ Type: WireGuard
├─ Egress IP: 203.0.113.200
├─ Last seen: 5 seconds ago
├─ Health: Healthy (200 OK)
└─ Routes using: 0

Step 4: Assign to Routes

Same as managed egress—assign the VPN node to routes via environment configuration.

Advanced Configuration

Multiple Egress Servers per Tenant

Use different egress IPs for different APIs:

Egress Servers:
├─ US East Egress (203.0.113.200)
│    Routes: Stripe, Twilio
│
├─ EU West Egress (198.51.100.50)
│    Routes: European banking APIs
│
└─ Corporate VPN (192.0.2.100)
     Routes: Internal partner APIs

Configuration:

Route A (Stripe) → uses US East Egress
Route B (European bank) → uses EU West Egress
Route C (partner) → uses Corporate VPN

Failover & High Availability

Managed egress servers:

Automatic health monitoring (every 30 seconds)
If unhealthy, routes fall back to direct routing
Email alerts on failover
Auto-recovery when health restored

Self-hosted VPN:

Manual health check URL (optional)
No automatic failover unless configured
You’re responsible for VPN uptime

Regional Routing

Route requests through the closest region to the destination API:

Your app in US → Stripe API in US
  ↓ uses US East Egress (low latency)

Your app in US → European Bank API in EU
  ↓ uses EU West Egress (compliance + latency)

Security Considerations

Managed Egress Servers

Isolation:

Dedicated Droplet per egress server (not shared)
Firewall rules restrict traffic to your routes only
No direct SSH access (managed via API)

Authentication:

Requests authenticated with tenant-specific secret
HMAC signature verification
Replay attack prevention

Monitoring:

All traffic logged
Health checks every 30 seconds
Alerts on anomalies

Self-Hosted VPN

Security checklist:

VPN credentials stored encrypted in KnoxCall
Firewall allows only KnoxCall server IPs
VPN configuration doesn’t expose internal network
Health check endpoint authenticated (if public)
Egress traffic monitored on your side

Network isolation:

Ensure VPN tunnel doesn’t grant KnoxCall access to internal network
Use split tunneling (only route API traffic through VPN)
Configure firewall rules on VPN gateway

Monitoring & Troubleshooting

Health Status

Check egress server health:

GET /admin/data-plane-nodes/{id}

Response:
{
  "id": "dpn_abc123",
  "status": "active",
  "last_seen_at": "2025-01-20T15:30:00Z",
  "health_check_url": "https://egress-health.knoxcall.com/ping",
  "egress_ip": "203.0.113.200",
  "region": "us-east-1"
}

Status values:

active - Healthy and routing traffic ✅
unhealthy - Failed health check ⚠️
unreachable - Cannot connect 🔴
provisioning - Being created 🔄

Request Logs

View which requests used egress routing:

GET /admin/logs

Response:
{
  "logs": [
    {
      "route_id": "route_abc123",
      "data_plane_node_id": "dpn_xyz789",
      "egress_ip": "203.0.113.200",
      "target_url": "https://api.stripe.com/v1/charges",
      "status": 200,
      "timestamp": "2025-01-20T15:30:00Z"
    }
  ]
}

Common Issues

Problem: “Egress server unreachable”

Routes using this server fall back to direct routing

Solutions:

Check server status in dashboard
If managed: wait 2-3 min for auto-recovery
If self-hosted: verify VPN server is running
Check firewall allows KnoxCall IPs

Problem: “API still rejecting IP”

API provider claims IP is not whitelisted

Debug steps:

Verify correct egress server assigned to route
Check route’s environment is correct
Test with: curl https://ifconfig.me/ip through egress server
Confirm API provider whitelisted the right IP
Check for typos in IP address (common!)

Problem: “Latency increased after enabling egress”

Requests now take 200ms longer

Causes:

Egress server in wrong region (e.g., US egress for EU API)
VPN has high latency

Solutions:

Use egress server closest to destination API
For self-hosted VPN: measure VPN latency
Consider multiple regional egress servers

Problem: “VPN connection keeps dropping”

Self-hosted VPN shows "unreachable" intermittently

Solutions:

Check VPN server logs for disconnections
Increase WireGuard PersistentKeepalive value
Configure health check to detect failures faster
Ensure firewall isn’t blocking keep-alive packets

Cost Optimization

When to Use Egress Routing

Use egress when:

✅ API requires IP whitelisting
✅ You need consistent source IP for logging/audit
✅ Compliance mandates specific egress points
✅ API has regional restrictions

Skip egress when:

❌ API doesn’t require IP whitelisting
❌ Added latency is critical (use direct routing)
❌ Route has very high traffic (cheaper to provision own server)

For enterprise deployments with many routes:

Option A: Separate egress per route
  → 10 routes = 10 egress servers = $290/month

Option B: Shared egress server
  → 10 routes = 1 egress server = $29/month
  → All use same egress IP

Most APIs accept multiple routes from same IP, so Option B is usually fine.

API Reference

Create Managed Egress Server

POST /admin/data-plane-nodes

{
  "kind": "managed",
  "display_name": "US East Egress",
  "region": "us-east-1"
}

Response:
{
  "id": "dpn_abc123",
  "status": "provisioning",
  "egress_ip": null,
  "estimated_ready_at": "2025-01-20T15:35:00Z"
}

Polling for completion:

GET /admin/data-plane-nodes/dpn_abc123

Response (when ready):
{
  "id": "dpn_abc123",
  "status": "active",
  "egress_ip": "203.0.113.200",
  "region": "us-east-1"
}

Register Self-Hosted VPN

POST /admin/data-plane-nodes

{
  "kind": "self_hosted",
  "display_name": "Corporate VPN",
  "vpn_type": "wireguard",
  "vpn_config_json": {
    "interface": {
      "private_key": "...",
      "address": "10.0.0.2/24"
    },
    "peer": {
      "public_key": "...",
      "endpoint": "vpn.corp.com:51820",
      "allowed_ips": "0.0.0.0/0"
    }
  },
  "egress_ip": "203.0.113.200",
  "health_check_url": "https://vpn-health.corp.com/ping"
}

Assign to Route Environment

PUT /admin/routes/{route_id}/environments/{environment_name}

{
  "data_plane_node_id": "dpn_abc123"
}

List All Egress Servers

GET /admin/data-plane-nodes

Response:
{
  "nodes": [
    {
      "id": "dpn_abc123",
      "display_name": "US East Egress",
      "kind": "managed",
      "region": "us-east-1",
      "egress_ip": "203.0.113.200",
      "status": "active",
      "routes_using_count": 5
    }
  ]
}

Delete Egress Server

DELETE /admin/data-plane-nodes/dpn_abc123

Response:
{
  "deleted": true,
  "routes_affected": 5,
  "fallback": "direct_routing"
}

Best Practices

✅ Do This

Test with dummy route first
- Create test route, assign egress, verify IP
- Don’t configure production routes immediately
Document which API requires which IP
- Keep spreadsheet of API → egress IP mappings
- Share with team for future reference
Set up alerts
- Email when egress server goes unhealthy
- Monitor latency changes
Use regional egress servers
- Match egress region to API region when possible
- Reduces latency
Keep egress credentials secure
- For self-hosted VPN, treat credentials as secrets
- Rotate VPN keys quarterly

❌ Avoid This

Don’t use same egress for unrelated APIs
- If one API blocks your IP, all routes affected
- Use separate egress servers for high-risk APIs
Don’t skip health checks for self-hosted VPN
- You’ll only discover downtime when users complain
- Set up health check URL
Don’t delete egress server while routes use it
- Routes will fall back to direct routing
- May break IP whitelisting
Don’t expose internal network via VPN
- Use split tunneling
- Firewall VPN gateway appropriately

Migration Guide

From Direct Routing to Egress

Before:

Route → Direct → API
(source IP changes)

After:

Route → Egress Server → API
(source IP: 203.0.113.200)

Steps:

Provision egress server
Get static IP
Contact API provider to whitelist IP
Wait for confirmation (don’t skip!)
Assign egress to route (test environment first)
Test
Assign to production
Monitor

Rollback plan:

Remove data_plane_node_id from route
Traffic reverts to direct routing

Next Steps

Multi-Region Deployment

Deploy KnoxCall across regions

Route Configuration

Learn about route setup

Monitoring

Monitor egress server health

Security

Secure your routes

📊 Guide Info

Level: Intermediate to Advanced
Time: 15-30 minutes
Prerequisites: Understanding of IP whitelisting and networking

🏷️ Tags

egress, vpn, networking, ip-whitelisting, infrastructure

Getting Started

Essentials: Routes

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Webhooks

Workflows

Security

Monitoring

Advanced Features

Infrastructure

Account

Troubleshooting

Support

About

​Egress IP Routing & VPN

​The Problem

​The Solution

​Types of Egress Routing

​1. Managed Egress Servers (Recommended)

​2. Self-Hosted VPN Integration

​Setting Up Managed Egress

​Step 1: Request Egress Server

​Step 2: Wait for Provisioning

​Step 3: Note Your Static IP

​Step 4: Assign to Routes

​Step 5: Test & Verify

​Setting Up Self-Hosted VPN

​Prerequisites

​Step 1: Prepare VPN Configuration

​Step 2: Register VPN in KnoxCall

​Step 3: Test Connection

​Step 4: Assign to Routes

​Advanced Configuration

​Multiple Egress Servers per Tenant

​Failover & High Availability

​Regional Routing

​Security Considerations

​Managed Egress Servers

​Self-Hosted VPN

​Monitoring & Troubleshooting

​Health Status

​Request Logs

​Common Issues

​Cost Optimization

​When to Use Egress Routing

​Multi-Tenant Cost Sharing

​API Reference

​Create Managed Egress Server

​Register Self-Hosted VPN

​Assign to Route Environment

​List All Egress Servers

​Delete Egress Server

​Best Practices

​✅ Do This

​❌ Avoid This

​Migration Guide

​From Direct Routing to Egress

​Next Steps

Multi-Region Deployment

Route Configuration

Monitoring

Security

📊 Guide Info

🏷️ Tags

Egress IP Routing & VPN

The Problem

The Solution

Types of Egress Routing

1. Managed Egress Servers (Recommended)

2. Self-Hosted VPN Integration

Setting Up Managed Egress

Step 1: Request Egress Server

Step 2: Wait for Provisioning

Step 3: Note Your Static IP

Step 4: Assign to Routes

Step 5: Test & Verify

Setting Up Self-Hosted VPN

Prerequisites

Step 1: Prepare VPN Configuration

Step 2: Register VPN in KnoxCall

Step 3: Test Connection

Step 4: Assign to Routes

Advanced Configuration

Multiple Egress Servers per Tenant

Failover & High Availability

Regional Routing

Security Considerations

Managed Egress Servers

Self-Hosted VPN

Monitoring & Troubleshooting

Health Status

Request Logs

Common Issues

Cost Optimization

When to Use Egress Routing

Multi-Tenant Cost Sharing

API Reference

Create Managed Egress Server

Register Self-Hosted VPN

Assign to Route Environment

List All Egress Servers

Delete Egress Server

Best Practices

✅ Do This

❌ Avoid This

Migration Guide

From Direct Routing to Egress

Next Steps