> ## 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.
# What are Clients?
> Understand IP whitelisting and client authorization in KnoxCall. Learn how clients provide network-level security.
# What are Clients?
A **client** in KnoxCall is an authorized IP address or network that's allowed to make requests through your routes. Think of clients as your "guest list" for API access.
## The Bouncer Analogy
Imagine KnoxCall as a nightclub bouncer:
* **Without clients**: Anyone on the internet can try to access your routes
* **With clients**: Only IPs on your whitelist get through the door
```text theme={"dark"}
Internet User (Random IP) → 🚫 Blocked
Your Server (Whitelisted) → ✅ Allowed
```
***
## What Problem Do Clients Solve?
### The Problem: Open Access
Without client authorization, your KnoxCall routes are accessible to anyone who knows the URL:
```bash theme={"dark"}
# Anyone can call this if they know your subdomain
curl https://a1b2c3d4.acme.knoxcall.com/api/users \
-H "x-knoxcall-route: user-api"
```
**Risks:**
* Attackers can spam your routes
* Unexpected traffic costs
* Potential DDoS attacks
* Unauthorized access attempts
### The Solution: IP Whitelisting
With client authorization enabled, only specific IP addresses can access your routes:
```text theme={"dark"}
Your Production Server (52.123.45.67) → ✅ Whitelisted
Your Office Network (203.14.0.0/16) → ✅ Whitelisted
Random Internet User (100.5.8.200) → ❌ BLOCKED
Attacker (45.67.89.10) → ❌ BLOCKED
```
***
## How Client Authorization Works
### The Request Flow
```text theme={"dark"}
1. Request arrives at KnoxCall
↓
2. KnoxCall extracts source IP address
↓
3. Checks if IP matches any authorized client
↓
4. If YES → Process route
If NO → Return 403 Forbidden
```
### Example
**Your clients:**
* Production server: `52.123.45.67`
* Staging server: `54.200.11.22`
**Request from production (52.123.45.67):**
```bash theme={"dark"}
curl https://a1b2c3d4.acme.knoxcall.com/api/users \
-H "x-knoxcall-route: user-api"
# ✅ Success: 200 OK
```
**Request from unknown IP (100.5.8.200):**
```bash theme={"dark"}
curl https://a1b2c3d4.acme.knoxcall.com/api/users \
-H "x-knoxcall-route: user-api"
# ❌ Error: 403 Forbidden
# "IP address not authorized for this route"
```
***
## Client Types
KnoxCall supports two types of clients:
### 1. Server (Recommended for Production)
**Best for**: Production servers with static IPs, office networks, cloud subnets
**Characteristics:**
* Fixed IP address or CIDR range (e.g., AWS Elastic IP or VPC subnet)
* Never changes
* Most reliable authorization method
**Examples:**
```text theme={"dark"}
Name: production-api-server
Type: Server
IP: 52.123.45.67
Description: Main API server (AWS us-east-1)
```
```text theme={"dark"}
Name: office-network
Type: Server
IP: 192.168.1.0/24
Description: Company office network (all employees)
```
### 2. User (For Development)
**Best for**: Developer machines, dynamic IPs
**Characteristics:**
* IP may change occasionally
* Great for local development
* Can be updated when IP changes
**Example:**
```text theme={"dark"}
Name: john-dev-laptop
Type: User
IP: 203.45.67.89
Description: John's development laptop
```
Both Server and User types support single IPs and CIDR ranges. The type is a label to help you organize — Server for infrastructure, User for people.
***
## IP Address Formats
### Single IP Address
Most common format for individual servers:
```text theme={"dark"}
52.123.45.67
```
Authorizes exactly one IP address.
### CIDR Notation (IP Ranges)
For networks and ranges:
```text theme={"dark"}
192.168.1.0/24
```
**What does `/24` mean?**
* Authorizes 192.168.1.0 through 192.168.1.255
* That's 256 IP addresses
**Common CIDR ranges:**
* `/32` = 1 IP (e.g., 192.168.1.1/32)
* `/24` = 256 IPs (e.g., 192.168.1.0/24)
* `/16` = 65,536 IPs (e.g., 10.0.0.0/16)
**Example office network:**
```text theme={"dark"}
Name: acme-corp-office
IP: 203.14.0.0/16
Description: All office locations
```
This authorizes:
* 203.14.0.1
* 203.14.0.2
* ... (all IPs from 203.14.0.0 to 203.14.255.255)
***
## Per-Environment Client Authorization
One of KnoxCall's most powerful features: **different clients for different environments**.
### The Concept
You can assign different sets of clients to:
* Production environment
* Staging environment
* Development environment
### Real-World Example
**Route**: `user-api`
**Production environment clients:**
* `52.123.45.67` (prod server)
* `52.123.45.68` (prod server backup)
**Staging environment clients:**
* `54.200.11.22` (staging server)
* `203.45.67.89` (your dev laptop)
**Result:**
* Production traffic comes from prod IPs only
* Staging can be accessed from staging server AND your laptop
* Clear separation between environments
***
## Common Use Cases
### 1. Production API Server
**Scenario**: Your backend server needs to call third-party APIs
**Setup:**
```text theme={"dark"}
Client:
Name: prod-api-server-1
Type: Server
IP: 52.123.45.67 (AWS Elastic IP)
Route: stripe-payments
Assigned Clients: prod-api-server-1
```
**Benefit**: Only your production server can charge customers via Stripe route.
### 2. Office Network
**Scenario**: Multiple team members need to test webhooks
**Setup:**
```text theme={"dark"}
Client:
Name: acme-office-network
Type: Server
IP: 203.14.0.0/24 (covers all office computers)
Route: test-webhooks
Assigned Clients: acme-office-network
```
**Benefit**: Everyone in the office can test, but external users can't.
### 3. Partner Integration
**Scenario**: External partner needs to send webhooks to your system
**Setup:**
```text theme={"dark"}
Client:
Name: partner-acme-corp
Type: Server
IP: 100.25.30.45 (partner's webhook server)
Route: partner-webhooks
Assigned Clients: partner-acme-corp
```
**Benefit**: Partner can send webhooks, but no one else can.
### 4. Development Team
**Scenario**: 5 developers working remotely with dynamic IPs
**Option A: Individual clients (tedious)**
```text theme={"dark"}
john-laptop: 203.45.67.89
jane-laptop: 180.123.45.67
bob-laptop: 192.5.8.100
...
```
**Option B: Use API key auth (better)**
* Create test API key with `skip_ip_check: true`
* Developers use API key instead of IP whitelist
* More flexible for dynamic IPs
***
## Client Priority and Fallback
### Assignment Levels
Clients can be assigned at two levels:
1. **Route-level (global)**: All environments use these clients
2. **Environment-level**: Specific clients per environment
**Environment-specific always wins:**
```text theme={"dark"}
Route "user-api":
Global clients: [prod-server, staging-server]
Environment "production":
Clients: [prod-server only]
Environment "staging":
Clients: [staging-server, dev-laptop]
```
**Result:**
* Production: Only `prod-server` allowed
* Staging: `staging-server` and `dev-laptop` allowed
* Global clients ignored when environment has specific clients
***
## Security Best Practices
### ✅ Do
* **Use specific IPs** - Don't whitelist entire internet ranges
* **Use CIDR for networks** - Easier to manage office networks
* **Separate environments** - Different clients for prod/staging/dev
* **Use descriptive names** - `prod-api-server-1` not `server1`
* **Document why** - Add descriptions explaining each client's purpose
* **Regular audits** - Remove unused clients monthly
### ❌ Don't
* **Don't use 0.0.0.0/0** - This allows ALL IPs (defeats the purpose!)
* **Don't reuse clients** - Production and staging should have separate clients
* **Don't forget to update** - When IPs change, update immediately
* **Don't whitelist untrusted IPs** - Only authorize systems you control
* **Don't use generic names** - `client1`, `client2` are unmaintainable
***
## IP Detection
KnoxCall automatically detects the source IP from these headers (in order):
1. **cf-connecting-ip** (Cloudflare - most reliable)
2. **x-forwarded-for** (Standard proxy header - first IP only)
3. **Socket remote address** (Direct connection fallback)
This ensures accurate IP detection even behind proxies and CDNs.
***
## When NOT to Use Clients
Client authorization might not be necessary if:
1. **Public webhooks** - Stripe, Shopify send from many IPs (use signature validation instead)
2. **CDN origins** - Cloudflare, Fastly have changing IP ranges (use request signing)
3. **Mobile apps** - Users have random IPs (use API key auth)
4. **Serverless functions** - Lambda, Cloud Functions have dynamic IPs (use API keys)
**Alternative**: Use request signing (`x-knoxcall-signature`) for these scenarios.
***
## Quick Reference
| Client Type | Best For | Example IP | Format |
| ----------- | ----------------------------------- | ---------------------------------- | ----------------------- |
| Server | Production servers, office networks | `52.123.45.67` or `192.168.1.0/24` | Single IP or CIDR range |
| User | Developer machines | `203.45.67.89` | Single IP or CIDR range |
***
## Next Steps
Step-by-step tutorial
Create, edit, delete, and assign clients
Deep dive into Server, User, and Network types
Understanding IP ranges
***
**Key Takeaway**: Clients are your first line of defense. They provide network-level security by ensuring only authorized IPs can access your routes.