> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting: IP Authorization Issues
> The #1 most common KnoxCall problem and how to fix it. Debug 'IP not authorized' errors quickly.
# 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:
```json theme={"dark"}
{
"error": "IP address not authorized for this route",
"status": 403,
"ip": "203.45.67.89"
}
```
Or:
```json theme={"dark"}
{
"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**
```bash theme={"dark"}
curl https://api.ipify.org
```
Output: `203.45.67.89`
**Step 2: Update your client in KnoxCall**
1. Go to **Resources** → **Clients**
2. Find your client (e.g., "john-dev-laptop")
3. Click **Edit**
4. Update IP to: `203.45.67.89`
5. 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:**
1. Navigate to **Resources** → **Clients**
2. Click **Create Client**
3. Fill in:
* **Name**: `my-dev-machine`
* **Type**: User
* **IP**: Your IP from `curl https://api.ipify.org`
4. Click **Save**
5. **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:**
1. Go to **Routes** → Find your route
2. Click on the route
3. Go to **Clients** tab
4. Select your environment (e.g., "production")
5. Check: Is your client listed?
**Solution:**
1. Click **Assign Clients**
2. Check the box next to your client
3. 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:**
```bash theme={"dark"}
# 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**
1. Go to route → **Clients** tab
2. Select "production"
3. Click **Assign Clients**
4. Check your client
5. Save
**Option B: Use correct environment in request**
```bash theme={"dark"}
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:**
1. Go to **Resources** → **Clients**
2. Find your client
3. Look at the **Enabled** column
4. Is it showing **OFF**?
**Solution:**
1. Click on the client
2. Toggle **Enabled** to **ON**
3. 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:**
```json theme={"dark"}
{
"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):
1. `cf-connecting-ip` (Cloudflare)
2. `x-forwarded-for` (Standard)
3. Socket remote address (fallback)
**If still wrong, whitelist the proxy IP:**
```text theme={"dark"}
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:**
```text theme={"dark"}
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**
```text theme={"dark"}
192.168.0.0/16 // Covers 192.168.0.0 to 192.168.255.255
```
**Option B: Create separate client**
```text theme={"dark"}
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**
1. Go to **Settings** → **Tenant** tab → **API Keys**
2. Click **Create API Key**
3. Name: `dev-test-key`
4. **Check**: Allow any IP ✓
5. Copy the key: `tk_abc123...`
**Step 2: Use in requests**
```bash theme={"dark"}
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:**
1. Go to **Routes** → Your route
2. Look for **Requires Clients** setting
3. Is it **OFF**?
**What this means:**
* **OFF** = Anyone can access (no IP check)
* **ON** = Only whitelisted clients can access
**Solution:**
1. Edit route
2. Toggle **Requires Clients** to **ON**
3. Save
***
## Debugging Checklist
Follow this checklist step-by-step:
### ✅ Step 1: Confirm Your IP
```bash theme={"dark"}
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 **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
```bash theme={"dark"}
# 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
1. Go to **Logs** → **API Logs**
2. Find your failed request
3. Look at error details
4. Check IP shown vs your actual IP
***
## Quick Tests
### Test 1: Temporarily Disable IP Check
To confirm IP authorization is the problem:
1. Edit your route
2. Toggle **Requires Clients** to **OFF**
3. Save
4. 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:
1. **Settings** → **Tenant** tab → **API Keys**
2. **Create API Key**
3. Name: `bypass-test-key`
4. **Allow any IP**: ✓
5. Use this key in requests:
```bash theme={"dark"}
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**
```text theme={"dark"}
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**
1. Allocate Elastic IP in AWS
2. Assign to your EC2 instance
3. Use Elastic IP in KnoxCall client
4. 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**
```text theme={"dark"}
API Key: dev-john (john@acme.com)
API Key: dev-jane (jane@acme.com)
API Key: dev-bob (bob@acme.com)
```
Each developer gets their own key, no IP management needed.
***
## Prevention Tips
### For Development
1. **Use API key auth** instead of IP whitelisting
2. Create separate test keys for each developer
3. Enable "Allow any IP" for dev keys only
### For Production
1. **Use static IPs** (Elastic IPs, static VPS IPs)
2. **Document your IPs** with descriptions
3. **Audit clients monthly** - remove unused ones
4. **Use CIDR ranges** for networks, not individual IPs
### For Staging
1. **Separate clients** from production
2. **Allow broader IP ranges** for easier testing
3. **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
1. **Firewall blocking**: Your firewall is changing source IP
2. **IPv4 vs IPv6**: Using IPv6 but whitelisted IPv4 (or vice versa)
3. **Rate limiting**: Hit rate limit, getting different error that looks similar
4. **Expired API key**: Using old/deleted API key
5. **Wrong subdomain**: Using wrong tenant subdomain
### Get Help
If none of these solutions work:
Fastest way to get help
Review detailed request logs
Deep dive into how clients work
Other error codes and solutions
***
## Summary: Most Common Fixes
**90% of IP authorization issues are one of these:**
1. ✅ **IP changed** → Update client IP
2. ✅ **Client not assigned to route** → Assign in Clients tab
3. ✅ **Wrong environment** → Check which environment you're calling
4. ✅ **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.