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

Name: production-api-server
Type: Server
IP: 52.123.45.67
Description: Main API server (AWS us-east-1)

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:

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:

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

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:

Route-level (global): All environments use these clients
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):

cf-connecting-ip (Cloudflare - most reliable)
x-forwarded-for (Standard proxy header - first IP only)
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:

Public webhooks - Stripe, Shopify send from many IPs (use signature validation instead)
CDN origins - Cloudflare, Fastly have changing IP ranges (use request signing)
Mobile apps - Users have random IPs (use API key auth)
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

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.

Getting Started

Essentials: Routes

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Essentials: Collections

Webhooks

Workflows

Security

Monitoring

Advanced Features

Infrastructure

Account

Troubleshooting

Support

About

​What are Clients?

​The Bouncer Analogy

​What Problem Do Clients Solve?

​The Problem: Open Access

​The Solution: IP Whitelisting

​How Client Authorization Works

​The Request Flow

​Example

​Client Types

​1. Server (Recommended for Production)

​2. User (For Development)

​IP Address Formats

​Single IP Address

​CIDR Notation (IP Ranges)

​Per-Environment Client Authorization

​The Concept

​Real-World Example

​Common Use Cases

​1. Production API Server

​2. Office Network

​3. Partner Integration

​4. Development Team

​Client Priority and Fallback

​Assignment Levels

​Security Best Practices

​✅ Do

​❌ Don’t

​IP Detection

​When NOT to Use Clients

​Quick Reference

​Next Steps

Create Your First Client

Managing Clients

Client Types

CIDR Notation

What are Clients?

The Bouncer Analogy

What Problem Do Clients Solve?

The Problem: Open Access

The Solution: IP Whitelisting

How Client Authorization Works

The Request Flow

Example

Client Types

1. Server (Recommended for Production)

2. User (For Development)

IP Address Formats

Single IP Address

CIDR Notation (IP Ranges)

Per-Environment Client Authorization

The Concept

Real-World Example

Common Use Cases

1. Production API Server

2. Office Network

3. Partner Integration

4. Development Team

Client Priority and Fallback

Assignment Levels

Security Best Practices

✅ Do

❌ Don’t

IP Detection

When NOT to Use Clients

Quick Reference

Next Steps