Troubleshooting: IP Authorization Issues

“IP address not authorized for this route” is the #1 most common error new KnoxCall users encounter. This guide will help you fix it quickly.

Symptoms

You make a request and receive:

{
  "error": "IP address not authorized for this route",
  "status": 403,
  "ip": "203.45.67.89"
}

Or:

{
  "error": "Client authorization required but IP not found",
  "status": 403
}

What this means: KnoxCall received your request but your IP address isn’t on the authorized client list for this route.

Quick Fix (Most Common Cause)

Problem: Your IP Changed

This is the #1 cause (especially for development machines). Your home/office internet likely uses dynamic IP addresses that change periodically.

Solution: Update Your Client IP

Step 1: Check your current IP

curl https://api.ipify.org

Output: 203.45.67.89 Step 2: Update your client in KnoxCall

Go to Resources → Clients
Find your client (e.g., “john-dev-laptop”)
Click Edit
Update IP to: 203.45.67.89
Click Save

Step 3: Try your request again ✅ Should work now!

Common Causes & Solutions

1. Client Not Created

Symptoms:

Fresh KnoxCall account
Never created any clients
Getting IP authorization errors

Cause: You haven’t whitelisted any IPs yet. Solution:

Navigate to Resources → Clients
Click Create Client
Fill in:
- Name: my-dev-machine
- Type: User
- IP: Your IP from curl https://api.ipify.org
Click Save
Assign client to route (see Cause #2)

2. Client Not Assigned to Route

Symptoms:

Client exists in KnoxCall
IP matches
Still getting 403 errors

Cause: Client exists, but it’s not assigned to this specific route. How to check:

Go to Routes → Find your route
Click on the route
Go to Environment Clients tab
Select your environment (e.g., “production”)
Check: Is your client listed?

Solution:

Click Assign Clients
Check the box next to your client
Click Save

✅ Client is now authorized for this route!

3. Wrong Environment

Symptoms:

Client is assigned to route
IP is correct
Still getting 403 errors

Cause: You’re calling one environment, but your client is assigned to a different one. Example:

# Calling production environment
curl https://a1b2c3d4.acme.knoxcall.com/api/users \
  -H "x-knoxcall-route: user-api" \
  -H "x-knoxcall-environment: production"

But your client is only assigned to staging environment! Solution: Option A: Assign to correct environment

Go to route → Environment Clients
Select “production”
Click Assign Clients
Check your client
Save

Option B: Use correct environment in request

curl https://a1b2c3d4.acme.knoxcall.com/api/users \
  -H "x-knoxcall-route: user-api" \
  -H "x-knoxcall-environment: staging"  # Changed to staging

4. Client Disabled

Symptoms:

Everything looks correct
Used to work
Suddenly stopped working

Cause: Someone disabled the client. How to check:

Go to Resources → Clients
Find your client
Look at the Enabled column
Is it showing OFF?

Solution:

Click on the client
Toggle Enabled to ON
Click Save

5. IP Detection Behind Proxy/CDN

Symptoms:

Your actual IP is correct in clients list
Still getting 403 with different IP shown in error

Cause: You’re behind a proxy (Cloudflare, Nginx, etc.) and KnoxCall is seeing the proxy IP, not your real IP. Example error:

{
  "error": "IP not authorized",
  "ip": "104.21.45.67"  // This is Cloudflare's IP, not yours!
}

Solution: KnoxCall automatically detects IPs from these headers (in order):

cf-connecting-ip (Cloudflare)
x-forwarded-for (Standard)
Socket remote address (fallback)

If still wrong, whitelist the proxy IP:

Client IP: 104.21.45.67 (the IP shown in error)

Or better, use API key authentication (see Cause #7).

6. CIDR Notation Mistake

Symptoms:

Using IP range (CIDR notation)
Some IPs work, some don’t

Cause: CIDR range doesn’t cover your actual IP. Example:

Client IP: 192.168.1.0/24
Your actual IP: 192.168.2.50

/24 covers 192.168.1.0 to 192.168.1.255 only. Your IP 192.168.2.50 is outside this range! Solution: Option A: Expand range

192.168.0.0/16  // Covers 192.168.0.0 to 192.168.255.255

Option B: Create separate client

Client 1: 192.168.1.0/24  (Office network A)
Client 2: 192.168.2.0/24  (Office network B)

CIDR Quick Reference:

/32 = 1 IP (e.g., 192.168.1.1 only)
/24 = 256 IPs (e.g., 192.168.1.0 to 192.168.1.255)
/16 = 65,536 IPs (e.g., 192.168.0.0 to 192.168.255.255)

7. Dynamic IP (Home Internet)

Symptoms:

Works sometimes
Stops working randomly
Home/office internet
Need to keep updating IP

Cause: Your ISP assigns dynamic IPs that change every few hours/days. Solution: Use API Key Auth (Recommended) Instead of IP whitelisting, use API key authentication: Step 1: Create test API key

Go to Settings → API Keys
Click Generate New Key
Name: dev-test-key
Check: Allow any IP ✓
Copy the key: tk_abc123...

Step 2: Use in requests

curl https://a1b2c3d4.acme.knoxcall.com/api/users \
  -H "x-knoxcall-key: tk_abc123..." \
  -H "x-knoxcall-route: user-api"

No more IP changes to worry about!

8. Route Has `requires_clients` Disabled

Symptoms:

Set up clients
Assigned to route
Still getting errors OR anyone can access

Cause: The route’s requires_clients flag is OFF. How to check:

Go to Routes → Your route
Look for Requires Clients setting
Is it OFF?

What this means:

OFF = Anyone can access (no IP check)
ON = Only whitelisted clients can access

Solution:

Edit route
Toggle Requires Clients to ON
Save

Debugging Checklist

Follow this checklist step-by-step:

✅ Step 1: Confirm Your IP

curl https://api.ipify.org

Write it down: ____________________

✅ Step 2: Check Client Exists

Go to Resources → Clients
Your IP is listed? (Exact match or in CIDR range)
Client is Enabled (toggle ON)?

✅ Step 3: Check Client Assignment

Go to Routes → Your route
Click Environment Clients tab
Select environment (production/staging/dev)
Your client is listed?

✅ Step 4: Check Route Settings

Route has Requires Clients = ON?
Route is Enabled = ON?

✅ Step 5: Verify Request Headers

# Are you sending the correct route name?
-H "x-knoxcall-route: YOUR_ROUTE_NAME"

# Are you specifying correct environment?
-H "x-knoxcall-environment: production"  # Optional

✅ Step 6: Check Logs

Go to Logs → API Logs
Find your failed request
Look at error details
Check IP shown vs your actual IP

Quick Tests

Test 1: Temporarily Disable IP Check

To confirm IP authorization is the problem:

Edit your route
Toggle Requires Clients to OFF
Save
Try your request again

If it works now: ✅ Confirmed: IP authorization was the issue ❌ If still fails: Different problem (not IP-related) Remember to turn Requires Clients back ON for production!

Test 2: Use Test API Key

Create an API key that bypasses IP check:

Settings → API Keys
Generate New Key
Name: bypass-test-key
Allow any IP: ✓
Use this key in requests:

curl https://a1b2c3d4.acme.knoxcall.com/api/test \
  -H "x-knoxcall-key: tk_test_bypass..." \
  -H "x-knoxcall-route: user-api"

If this works: Definitely an IP whitelisting issue.

Advanced Scenarios

VPN Users

Problem: Your IP changes when VPN connects/disconnects. Solution A: Whitelist VPN IP range

Client IP: 10.8.0.0/16  (entire VPN network)

Solution B: Use API key auth (See Cause #7 above)

AWS/Cloud Servers

Problem: EC2 instances with dynamic IPs. Solution: Use Elastic IP

Allocate Elastic IP in AWS
Assign to your EC2 instance
Use Elastic IP in KnoxCall client
IP never changes!

Cost: ~$3.60/month for unused Elastic IP (free when attached to running instance)

Docker/Kubernetes

Problem: Container IPs change on restart. Solution: Use NAT gateway or API key auth Don’t whitelist: Container internal IPs (172.17.0.2, etc.) Do whitelist: NAT gateway public IP or load balancer IP

Multiple Developers

Problem: 10 developers, each with changing IPs. Solution: Use test API keys per developer

API Key: dev-john ([email protected])
API Key: dev-jane ([email protected])
API Key: dev-bob ([email protected])

Each developer gets their own key, no IP management needed.

Prevention Tips

For Development

Use API key auth instead of IP whitelisting
Create separate test keys for each developer
Enable “Allow any IP” for dev keys only

For Production

Use static IPs (Elastic IPs, static VPS IPs)
Document your IPs with descriptions
Audit clients monthly - remove unused ones
Use CIDR ranges for networks, not individual IPs

For Staging

Separate clients from production
Allow broader IP ranges for easier testing
Use descriptive names (staging-server-1, not server1)

Error Message Reference

Error Message	Meaning	Most Common Cause
`IP address not authorized for this route`	Your IP isn’t whitelisted	IP changed or not assigned to route
`Client authorization required but IP not found`	No matching client	Never created a client
`Route requires client authorization`	Route has IP check enabled	Forgot to assign client
`No clients assigned to environment`	Environment has no clients	Assigned to wrong environment

Still Having Issues?

Check These Less Common Causes

Firewall blocking: Your firewall is changing source IP
IPv4 vs IPv6: Using IPv6 but whitelisted IPv4 (or vice versa)
Rate limiting: Hit rate limit, getting different error that looks similar
Expired API key: Using old/deleted API key
Wrong subdomain: Using wrong tenant subdomain

Get Help

If none of these solutions work:

Support Chat

Fastest way to get help

Check Logs

Review detailed request logs

Client Documentation

Deep dive into how clients work

Common Errors

Summary: Most Common Fixes

90% of IP authorization issues are one of these:

✅ IP changed → Update client IP
✅ Client not assigned to route → Assign in Environment Clients
✅ Wrong environment → Check which environment you’re calling
✅ Dynamic IP → Use API key auth instead

Quick fix for development: Use API key with “Allow any IP” enabled. No more IP hassles!

Security Note: Only use “Allow any IP” API keys for development/testing. Production keys should always validate IP addresses for security.

Getting Started

Essentials: Routes

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Webhooks

Workflows

Security

Monitoring

Advanced Features

Infrastructure

Account

Troubleshooting

Support

About

​Troubleshooting: IP Authorization Issues

​Symptoms

​Quick Fix (Most Common Cause)

​Problem: Your IP Changed

​Solution: Update Your Client IP

​Common Causes & Solutions

​1. Client Not Created

​2. Client Not Assigned to Route

​3. Wrong Environment

​4. Client Disabled

​5. IP Detection Behind Proxy/CDN

​6. CIDR Notation Mistake

​7. Dynamic IP (Home Internet)

​8. Route Has requires_clients Disabled

​Debugging Checklist

​✅ Step 1: Confirm Your IP

​✅ Step 2: Check Client Exists

​✅ Step 3: Check Client Assignment

​✅ Step 4: Check Route Settings

​✅ Step 5: Verify Request Headers

​✅ Step 6: Check Logs

​Quick Tests

​Test 1: Temporarily Disable IP Check

​Test 2: Use Test API Key

​Advanced Scenarios

​VPN Users

​AWS/Cloud Servers

​Docker/Kubernetes

​Multiple Developers

​Prevention Tips

​For Development

​For Production

​For Staging

​Error Message Reference

​Still Having Issues?

​Check These Less Common Causes

​Get Help

Support Chat

Check Logs

Client Documentation

Common Errors

​Summary: Most Common Fixes

Troubleshooting: IP Authorization Issues

Symptoms

Quick Fix (Most Common Cause)

Problem: Your IP Changed

Solution: Update Your Client IP

Common Causes & Solutions

1. Client Not Created

2. Client Not Assigned to Route

3. Wrong Environment

4. Client Disabled

5. IP Detection Behind Proxy/CDN

6. CIDR Notation Mistake

7. Dynamic IP (Home Internet)

8. Route Has `requires_clients` Disabled

Debugging Checklist

✅ Step 1: Confirm Your IP

✅ Step 2: Check Client Exists

✅ Step 3: Check Client Assignment

✅ Step 4: Check Route Settings

✅ Step 5: Verify Request Headers

✅ Step 6: Check Logs

Quick Tests

Test 1: Temporarily Disable IP Check

Test 2: Use Test API Key

Advanced Scenarios

VPN Users

AWS/Cloud Servers

Docker/Kubernetes

Multiple Developers

Prevention Tips

For Development

For Production

For Staging

Error Message Reference

Still Having Issues?

Check These Less Common Causes

Get Help

Summary: Most Common Fixes