Skip to main content

​
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 
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 
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: 
curl https://api.ipify.org
Your server’s IP: 
curl https://api.ipify.org
# Run this command on your server
IP range (CIDR): Use a calculator like https://www.ipaddressguide.com/cidr

​
Step 2: Navigate to Clients

  1. Click Resources in sidebar
  2. Select Clients
  3. Click Add Client

​
Step 3: Fill in Client Details

Client Name: 
Production App Server
Descriptive name for this IP/range Type: Select one
  • Server: Backend servers, static IPs
  • User: Development machines, laptops
IP Address: 
52.123.45.67
Or CIDR range like 192.168.1.0/24 Multiple IPs (comma-separated): 
52.123.45.67,52.123.45.68,52.123.45.69
Description (optional): 
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 Environment Clients Tab

Click the Environment 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

# 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

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

​
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 
52.123.45.67,52.123.45.68,52.123.45.69
Or: 
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:

Environments

Assign different clients per environment

Request Signing

Add HMAC signatures for extra security

Secrets

Add encrypted credentials to requests

Rate Limiting

Limit requests per client
  • 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

📊 Statistics

  • Level: beginner
  • Time: 5 minutes

🏷️ Tags

clients, ip-whitelist, security, authorization