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 (DigitalOcean region slugs):

🇺🇸 nyc3 — New York, USA
🇺🇸 sfo3 — San Francisco, USA
🇬🇧 lon1 — London, UK
🇩🇪 fra1 — Frankfurt, Germany
🇳🇱 ams3 — Amsterdam, Netherlands
🇦🇺 syd1 — Sydney, Australia
🇸🇬 sgp1 — Singapore

Pricing:

Included in Pro 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 Proxy → Static IPs (cloud-hosted KnoxCall only — this page is hidden on self-hosted deployments)
Click Request Static IP
Configure:

Type: shared        # or "dedicated" (Enterprise only)
Region: nyc3        # DigitalOcean region slug — New York

Click Request

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: nyc3 (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}/egress

{
  "egress_server_id": "<egress-server-uuid>"
}

Pass egress_server_id: null to remove the egress assignment and revert the route to direct routing.

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 the VPN page and click Create VPN Connection → My Own VPN
Choose your VPN type (WireGuard, OpenVPN, or custom proxy)
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

Assign the VPN node to a route from the route detail page under Advanced → Egress Routing.

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

Managed egress servers — run an on-demand health check:

GET /admin/egress/{server_id}/health

Response:
{
  "server_id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
  "healthy": true,
  "checked_at": "2025-01-20T15:30:00Z"
}

Self-hosted VPN nodes — read the node’s current status:

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

Response:
{
  "id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
  "status": "active",
  "last_seen_at": "2025-01-20T15:30:00Z",
  "health_check_url": "https://vpn-health.corp.com/ping",
  "egress_ip": "203.0.113.200",
  "region": "nyc3"
}

IDs are UUIDs. To actively test a self-hosted node’s connectivity, call POST /admin/data-plane-nodes/{id}/test. Status values:

active - Healthy and routing traffic ✅
unhealthy - Failed health check ⚠️
unreachable - Cannot connect 🔴
unknown - Status not yet determined 🔄

Request Logs

View which requests used egress routing:

GET /admin/logs

Response:
{
  "logs": [
    {
      "route_id": "3a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "data_plane_node_id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
      "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

Managed egress servers have their own API surface under /admin/egress. The data-plane-node endpoints (/admin/data-plane-nodes) are for self-hosted VPN nodes. All of these endpoints are cloud-mode only.

Supporting endpoints

GET /admin/egress/regions              # list available DigitalOcean regions
GET /admin/egress/pricing              # shared / dedicated monthly pricing
GET /admin/egress/availability/{region}  # is a shared server available now?

Request a Managed Egress IP

POST /admin/egress

{
  "type": "shared",   // "shared" or "dedicated" (dedicated = Enterprise)
  "region": "nyc3"    // DigitalOcean region slug (default: syd1)
}

Response:
{
  "ok": true,
  "message": "No shared server available in this region. Provisioning new server (2-3 minutes).",
  "is_provisioning": true,
  "egress_server": {
    "id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
    "ip_address": null,
    "region": "nyc3",
    "type": "shared",
    "status": "provisioning"
  }
}

Polling for completion:

GET /admin/egress

Response (when ready):
{
  "egress_servers": [
    {
      "id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
      "status": "active",
      "reserved_ip": "203.0.113.200",
      "region": "nyc3"
    }
  ]
}

If provisioning fails, retry with POST /admin/egress/{server_id}/retry.

Register Self-Hosted VPN

region, kind, and display_name are required. kind must be managed or self_hosted; vpn_type (when present) must be wireguard, openvpn, or custom. vpn_config_json is a free-form blob stored verbatim — its shape is not validated, so the keys below are just an example.

POST /admin/data-plane-nodes

{
  "kind": "self_hosted",
  "region": "nyc3",
  "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"
}

Response:
{
  "id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
  "status": "unknown",
  ...
}

The response returns the full node row; id is a UUID.

Update / Test a Self-Hosted Node

PUT  /admin/data-plane-nodes/{id}        # update node fields (partial; fields are COALESCEd)
POST /admin/data-plane-nodes/{id}/test   # test VPN connectivity → { healthy, status, last_seen_at }

Assign Egress Server to a Route

PUT /admin/routes/{route_id}/egress

{
  "egress_server_id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b"
}

Send "egress_server_id": null to clear the assignment and revert to direct routing.

List Managed Egress Servers

GET /admin/egress

Response:
{
  "egress_servers": [
    {
      "id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
      "reserved_ip": "203.0.113.200",
      "region": "nyc3",
      "type": "shared",
      "status": "active"
    }
  ]
}

Self-hosted VPN nodes are listed separately via GET /admin/data-plane-nodes (returns { "nodes": [...] }).

Release a Managed Egress Server

DELETE /admin/egress/{server_id}

Response:
{
  "ok": true,
  "message": "Egress IP allocation released"
}

A server cannot be released while any route still uses it (returns 400 with routes_using).

Check Managed Egress Health

GET /admin/egress/{server_id}/health

Response:
{
  "server_id": "9f1c0e2a-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
  "healthy": true,
  "checked_at": "2025-01-20T15:30:00Z"
}

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:

Clear the egress assignment (PUT /admin/routes/{route_id}/egress with "egress_server_id": null)
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

​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

​Supporting endpoints

​Request a Managed Egress IP

​Register Self-Hosted VPN

​Update / Test a Self-Hosted Node

​Assign Egress Server to a Route

​List Managed Egress Servers

​Release a Managed Egress Server

​Check Managed Egress Health

​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

Supporting endpoints

Request a Managed Egress IP

Register Self-Hosted VPN

Update / Test a Self-Hosted Node

Assign Egress Server to a Route

List Managed Egress Servers

Release a Managed Egress Server

Check Managed Egress Health

Best Practices

✅ Do This

❌ Avoid This

Migration Guide

From Direct Routing to Egress

Next Steps