> ## 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.
# Creating Your First Client
> Secure your routes with IP whitelisting. Learn how to create clients and assign them to routes.
# Creating Your First Client
Add IP-based access control to your routes by creating and assigning clients.
## What is a Client?
A **client** in KnoxCall represents an **authorized IP address** or IP range that can access your routes. This provides network-level security in addition to API key authentication.
**Important**: Clients are NOT the same as API keys!
* **API keys** = Authentication (who you are)
* **Clients** = Authorization (where you're calling from)
Both are checked for secure routes.
## Why Use Clients?
**Without clients** (client IP authorization disabled):
* Anyone with your API key can call your routes from anywhere
* Higher risk if API key is leaked
**With clients** (client IP authorization enabled):
* Only whitelisted IPs can call routes, even with a valid API key
* Defense-in-depth security model
* Useful for server-to-server integrations
## Client Types
### Server Clients
**Use case**: Backend servers with static IPs
**Examples**:
* Your production app server (`52.123.45.67`)
* Office network (`192.168.1.0/24`)
* Cloud function with fixed egress IP
**IP Format**: Single IP or CIDR range
```text theme={"dark"}
52.123.45.67
192.168.1.0/24
10.0.0.0/16
```
### User Clients
**Use case**: Development machines, mobile devices
**Examples**:
* Your laptop for testing
* Team member workstations
* VPN exit nodes
**IP Format**: Usually single IPs
```text theme={"dark"}
203.45.67.89
```
User IPs often change (mobile networks, home ISPs). For production, prefer server clients with static IPs.
## Create a Client
### Step 1: Find Your IP Address
First, determine what IP address to whitelist:
**Your current IP:**
```bash theme={"dark"}
curl https://api.ipify.org
```
**Your server's IP:**
```bash theme={"dark"}
curl https://api.ipify.org
# Run this command on your server
```
**IP range (CIDR):** Use a calculator like [https://www.ipaddressguide.com/cidr](https://www.ipaddressguide.com/cidr)
### Step 2: Navigate to Clients
1. Open the **Proxy** section in the sidebar
2. Select **Clients**
3. Click **Add Client**
### Step 3: Fill in Client Details
**Client Name:**
```text theme={"dark"}
Production App Server
```
*Descriptive name for this IP/range*
**Type:** Select one
* **Server**: Backend servers, static IPs
* **User**: Development machines, laptops
**IP Address:**
```text theme={"dark"}
52.123.45.67
```
*Or CIDR range like `192.168.1.0/24`*
**Multiple IPs** (comma-separated):
```text theme={"dark"}
52.123.45.67,52.123.45.68,52.123.45.69
```
**Description** (optional):
```text theme={"dark"}
AWS EC2 production instance in us-east-1
```
**Enabled:** ✓ ON
### Step 4: Save
Click **Create Client**
Your client is created but NOT yet assigned to any routes.
## Assign Client to a Route
Clients must be assigned to specific routes and environments to grant access.
### Step 1: Open Your Route
1. Navigate to **Routes**
2. Click your route (e.g., "my-first-route")
### Step 2: Go to Clients Tab
Click the **Clients** tab
This shows which clients are allowed for each environment.
### Step 3: Assign Client
1. Find the environment (e.g., "production")
2. Click **Assign Clients**
3. Select your client from the list
4. Click **Save**
Now requests from that IP can access this route (in this environment)!
## Test Client Access
### From Authorized IP
```bash theme={"dark"}
# Should work (200 OK)
curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
-H "x-knoxcall-key: tk_abc123..." \
-H "x-knoxcall-route: my-first-route"
```
### From Unauthorized IP
```bash theme={"dark"}
# Should fail (403 Forbidden)
# Try from different machine/network
curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
-H "x-knoxcall-key: tk_abc123..." \
-H "x-knoxcall-route: my-first-route"
# Response:
# {"error": "IP not authorized"}
```
## Client Connectivity Check
KnoxCall can ping your server clients to verify they're online.
### Run Connectivity Test
1. Go to **Clients** page
2. Find your server client
3. Click **Ping** button
**Online**: Green checkmark ✅
**Offline**: Red X ❌
This is useful for monitoring server health.
Ping requires ICMP to be allowed. If your server blocks ICMP, the ping will fail even if the server is online.
## Advanced: CIDR Ranges
CIDR notation allows you to whitelist entire subnets.
**Common ranges:**
```text theme={"dark"}
192.168.1.0/24 → 192.168.1.0 - 192.168.1.255 (256 IPs)
10.0.0.0/16 → 10.0.0.0 - 10.0.255.255 (65,536 IPs)
172.16.0.0/12 → 172.16.0.0 - 172.31.255.255 (1,048,576 IPs)
```
**Use cases:**
* Office network: `192.168.1.0/24`
* AWS VPC: `10.0.0.0/16`
* Cloud provider IP range: Specific to provider
**Calculator:** [https://www.ipaddressguide.com/cidr](https://www.ipaddressguide.com/cidr)
## Disable Client IP Authorization
To allow requests from any IP (with valid API key only):
1. Edit your route
2. Find **Requires Clients** toggle
3. Turn it OFF
4. Save
Only disable for public routes or testing. Production routes should use client IP authorization.
## Multiple Clients per Route
You can assign multiple clients to a route:
**Example scenario:**
* `office-network` → `192.168.1.0/24`
* `aws-prod-server-1` → `52.123.45.67`
* `aws-prod-server-2` → `52.123.45.68`
All three can access the route.
## Environment-Specific Clients
Clients are assigned **per environment**. This lets you use different IPs for dev/staging/production:
**Development environment:**
* `dev-laptop` → `203.45.67.89`
**Staging environment:**
* `staging-server` → `34.56.78.90`
**Production environment:**
* `prod-server-1` → `52.123.45.67`
* `prod-server-2` → `52.123.45.68`
Same route, different allowed IPs per environment!
## Common Issues
### "IP not authorized" Error
**Causes:**
1. Your IP isn't whitelisted
2. Client not assigned to route environment
3. Client is disabled
4. Your IP changed (mobile/home networks)
5. Request is going through proxy/CDN with different IP
**Debug:**
1. Check actual IP: `curl https://api.ipify.org`
2. Compare with whitelisted IP in client settings
3. Verify client is assigned to route + environment
4. Check client is enabled
5. Look at request logs to see incoming IP
### Client Shows Offline
**Causes:**
* ICMP (ping) blocked by firewall
* Server is actually down
* Network routing issues
**Not a blocker**: Routes still work if connectivity check fails
### Multiple IPs Needed
**Solution**: Use CIDR ranges or comma-separated IPs
```text theme={"dark"}
52.123.45.67,52.123.45.68,52.123.45.69
```
Or:
```text theme={"dark"}
52.123.45.64/28 (includes .65 through .78)
```
### IP Changes Frequently
**For development:**
* Use test API keys (skip IP check)
* Or temporarily disable `requires_clients`
**For production:**
* Use static IPs (elastic IPs on AWS, etc.)
* Or use VPN with fixed egress IP
* Or use cloud provider IP ranges
## Security Best Practices
✅ **Do:**
* Use static IPs for production clients
* Combine with API key authentication
* Use CIDR ranges for office networks
* Enable connectivity monitoring
* Document client purpose in description
❌ **Don't:**
* Use `0.0.0.0/0` (allows all IPs - defeats the purpose)
* Add untrusted IPs to production routes
* Forget to remove old/unused clients
* Share clients across unrelated routes
## Next Steps
Now that you understand clients:
Assign different clients per environment
Add HMAC signatures for extra security
Add encrypted credentials to requests
Limit requests per client
## Related Concepts
* **API Keys**: Authentication layer (who you are)
* **Clients**: Authorization layer (where you're calling from)
* **Environments**: Different client sets for dev/staging/prod
* **Request Signing**: Additional verification via HMAC signatures
***
* **Level**: beginner
* **Time**: 5 minutes
`clients`, `ip-whitelist`, `security`, `authorization`