Skip to main content

​
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
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: 
# 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: 
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

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): 
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): 
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 three types of clients: Best for: Production servers with static IPs Characteristics:
  • Fixed IP address (e.g., AWS Elastic IP)
  • Never changes
  • Most reliable authorization method
Example: 
Name: production-api-server
Type: Server
IP: 52.123.45.67
Description: Main API server (AWS us-east-1)

​
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: 
Name: john-dev-laptop
Type: User
IP: 203.45.67.89
Description: John's development laptop

​
3. Network (For IP Ranges)

Best for: Office networks, VPNs, cloud providers Characteristics:
  • Covers entire IP range using CIDR notation
  • All IPs in range are authorized
  • Convenient for large teams
Example: 
Name: office-network
Type: Network
IP: 192.168.1.0/24
Description: Company office network (all employees)

​
IP Address Formats

​
Single IP Address

Most common format for individual servers: 
52.123.45.67
Authorizes exactly one IP address.

​
CIDR Notation (IP Ranges)

For networks and ranges: 
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: 
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: 
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: 
Client:
  Name: acme-office-network
  Type: Network
  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: 
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) 
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: 
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 TypeBest ForExample IPFormat
ServerProduction servers52.123.45.67Single IP
UserDeveloper machines203.45.67.89Single IP
NetworkOffice networks, VPNs192.168.1.0/24CIDR range

​
Next Steps

Create Your First Client

Step-by-step tutorial

Managing Clients

Create, edit, delete, and assign clients

Client Types

Deep dive into Server, User, and Network types

CIDR Notation

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.