Skip to main content

​
Managing Clients

Complete guide to creating, editing, deleting, and assigning clients for IP authorization.

​
Creating Clients

​
Step 1: Navigate to Clients

  1. Click Resources in the sidebar
  2. Select Clients
  3. Click Create Client button

​
Step 2: Fill in Client Details

​
Name (Required)

Give your client a descriptive name. Good examples: 
production-api-server-1
staging-server-aws
john-dev-laptop
office-network-main
partner-acme-webhook-server
Bad examples: 
client1          (not descriptive)
server           (too generic)
test             (what is this?)

​
Type (Required)

Choose the appropriate type:
TypeBest ForExample
ServerProduction servers with static IPsAWS EC2 with Elastic IP
UserDeveloper machines, dynamic IPsLaptops, home offices
NetworkIP ranges, office networks192.168.1.0/24
Recommendation: Use Server for production, User for development.

​
IP Address (Required)

Enter the IP address or CIDR range. Single IP: 
52.123.45.67
IP Range (CIDR): 
192.168.1.0/24    (256 IPs: .0 to .255)
10.0.0.0/16       (65,536 IPs)
203.14.0.0/24     (256 IPs for office)
How to find your IP: 
curl https://api.ipify.org
Document what this client is for. Good descriptions: 
"Main production API server in AWS us-east-1"
"John's development MacBook Pro"
"Office network - all floors"
"Partner XYZ webhook callback server"
"Staging environment in GCP"

​
Enabled Toggle

  • ON (default): Client is active and authorized
  • OFF: Client is disabled, requests will be rejected

​
Step 3: Save

Click Create Client ✅ Client is now created but not yet assigned to any routes!

​
Assigning Clients to Routes

Creating a client doesn’t automatically authorize it. You must assign it to specific routes.

​
Method 1: Assign from Route Page

Best for: Assigning to one route
  1. Go to Routes
  2. Click on your route
  3. Go to Environment Clients tab
  4. Select environment (e.g., “production”)
  5. Click Assign Clients
  6. Check the boxes next to clients you want to authorize
  7. Click Save
✅ Those clients can now access this route in that environment!

​
Method 2: Assign from Client Page

Best for: Assigning one client to multiple routes
  1. Go to Resources → Clients
  2. Click on your client
  3. Go to Assigned Routes tab
  4. Click Assign to Routes
  5. Select routes and environments
  6. Click Save

​
Per-Environment Assignment

Clients can be assigned differently per environment.

​
Example Setup

Route: user-api Production environment:
  • Clients: prod-server-1, prod-server-2
Staging environment:
  • Clients: staging-server, qa-laptop-1, qa-laptop-2
Development environment:
  • Clients: dev-laptop-1, dev-laptop-2, dev-laptop-3

​
How to Assign Per Environment

  1. Go to route → Environment Clients tab
  2. Select environment dropdown (e.g., “production”)
  3. Click Assign Clients
  4. Check clients for this environment only
  5. Save
  6. Repeat for each environment
Result:
  • Production requests only work from production servers
  • Staging requests work from staging + QA machines
  • Dev requests work from developer laptops

​
Editing Clients

​
When to Edit

Common reasons to edit:
  • IP address changed (especially for User type)
  • Need to update description
  • Need to enable/disable temporarily
  • Expanding IP range (CIDR)

​
How to Edit

  1. Go to Resources → Clients
  2. Find your client in the list
  3. Click on the client name
  4. Click Edit button
  5. Update fields as needed
  6. Click Save

​
Common Edits

​
Update IP Address

When: Your development machine IP changed Before: 
IP: 203.45.67.89
After: 
IP: 203.45.67.100
How to check current IP: 
curl https://api.ipify.org

​
Expand IP Range

When: Need to cover more IPs Before: 
IP: 192.168.1.0/24   (covers .0 to .255)
After: 
IP: 192.168.0.0/16   (covers .0.0 to .255.255)

​
Change Type

When: Server gets static IP Before: 
Type: User
IP: 203.45.67.89  (dynamic)
After: 
Type: Server
IP: 52.123.45.67  (Elastic IP - static)

​
Enabling/Disabling Clients

​
Temporarily Disable

When to use:
  • Testing without deleting
  • Temporarily block access
  • Troubleshooting
How:
  1. Edit client
  2. Toggle Enabled to OFF
  3. Save
Result: Client exists but requests are rejected.

​
Re-Enable

How:
  1. Edit client
  2. Toggle Enabled to ON
  3. Save
Result: Client is active again.

​
Deleting Clients

​
When to Delete

  • Client is no longer needed
  • IP is permanently decommissioned
  • Cleaning up old test clients
  • Security: remove unauthorized access

​
⚠️ Warning

Deleting a client is permanent and will:
  • Remove client from ALL routes
  • Reject all future requests from this IP
  • Cannot be undone
Make sure you want to delete!

​
How to Delete

  1. Go to Resources → Clients
  2. Find your client
  3. Click on client name
  4. Click Delete button
  5. Confirm deletion
✅ Client is permanently removed.

​
Safe Alternative: Disable Instead

Instead of deleting, consider disabling:
  • Keeps configuration
  • Can be re-enabled later
  • Reversible

​
Viewing Client Information

​
Client Details Page

Click on any client to see: Basic Info:
  • Name, Type, IP address
  • Description
  • Enabled status
  • Created date
Assigned Routes:
  • Which routes this client can access
  • Which environments it’s assigned to
Activity Log:
  • Recent requests from this IP
  • Success/failure rate
  • Last seen timestamp

​
Bulk Operations

​
Assign Multiple Clients at Once

Scenario: Add 5 developer laptops to dev environment Steps:
  1. Go to route → Environment Clients
  2. Select “development”
  3. Click Assign Clients
  4. Check all 5 developer clients at once
  5. Save
✅ All 5 clients assigned in one operation!

​
Create Multiple Clients from CSV

Not currently supported in UI - Need to create one by one. Workaround for many clients: Use KnoxCall API to script client creation: 
for ip in $(cat ip_list.txt); do
  curl -X POST https://admin.knoxcall.com/api/clients \
    -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
    -d "{\"name\": \"server-$ip\", \"ip\": \"$ip\", \"type\": \"server\"}"
done

​
Client Organization

​
Naming Convention

Use consistent naming for easy management: Pattern: {environment}-{purpose}-{identifier} Examples: 
prod-api-server-1
prod-api-server-2
staging-app-server
dev-john-laptop
dev-jane-laptop
office-network-floor-1
partner-stripe-webhook

​
Use Descriptions

Always add descriptions to remember purpose: 
Name: prod-api-server-1
Description: Main production API server in AWS us-east-1, Elastic IP 52.123.45.67

Name: dev-john-laptop
Description: John's MacBook Pro for local development, IP changes frequently

Name: office-network
Description: Main office Wi-Fi network covering all floors, 192.168.1.0/24

​
Common Scenarios

​
Scenario 1: New Developer Joins

Steps:
  1. Ask developer for their IP: curl https://api.ipify.org
  2. Create client:
    • Name: dev-alice-laptop
    • Type: User
    • IP: 203.50.60.70
  3. Assign to development environment of all necessary routes
  4. Developer can now test locally!

​
Scenario 2: Move to Production

Steps:
  1. Provision production server with static IP (Elastic IP)
  2. Create client:
    • Name: prod-api-server-1
    • Type: Server
    • IP: 52.100.200.50 (Elastic IP)
  3. Assign to production environment only (not staging/dev)
  4. Test carefully before going live

​
Scenario 3: Office Network

Steps:
  1. Get office network CIDR range: 192.168.1.0/24
  2. Create client:
    • Name: office-network-main
    • Type: Network
    • IP: 192.168.1.0/24
  3. Assign to staging or dev environments (not production!)
  4. All office computers can now access

​
Scenario 4: IP Changed Unexpectedly

Symptoms: Requests suddenly fail with “IP not authorized” Steps:
  1. Check current IP: curl https://api.ipify.org
  2. Compare to client IP in KnoxCall
  3. If different → Edit client
  4. Update IP to new value
  5. Save → Requests work again!
Prevention for dev: Use API key auth instead of IP whitelisting (see below).

​
Alternative: API Key Authentication

For environments with dynamic IPs, consider using API key auth instead:

​
When to Use API Keys Instead

  • Developer laptops (IP changes frequently)
  • Mobile devices
  • Serverless functions (Lambda, Cloud Functions)
  • Behind CDN/proxy with changing IPs

​
How to Set Up

  1. Create API key in Settings → API Keys
  2. Enable “Allow any IP” for dev/test keys
  3. Use key in requests instead of IP whitelisting
Request with API key: 
curl https://a1b2c3d4.acme.knoxcall.com/api/users \
  -H "x-knoxcall-key: tk_dev_abc123..." \
  -H "x-knoxcall-route: user-api"
No IP whitelisting needed! Note: Only use “Allow any IP” for dev/test keys, never production.

​
Security Best Practices

​
✅ Do

  1. Use descriptive names - Know what each client is for
  2. Add descriptions - Document IP source and purpose
  3. Use static IPs for production - Elastic IPs, not dynamic
  4. Separate environments - Different clients for prod/staging/dev
  5. Regular audits - Review and remove unused clients monthly
  6. Least privilege - Only assign to routes that need it

​
❌ Don’t

  1. Don’t use 0.0.0.0/0 - This allows ALL IPs (defeats purpose!)
  2. Don’t share clients - Production and dev should have separate clients
  3. Don’t ignore changes - Update IPs promptly when they change
  4. Don’t use generic names - “client1”, “test” are confusing
  5. Don’t allow dev IPs in prod - Keep environments isolated

​
Troubleshooting

​
Client Created But Requests Rejected

Cause: Client not assigned to route. Solution:
  1. Go to route → Environment Clients
  2. Select environment
  3. Assign your client
  4. Try again

​
IP Keeps Changing

Cause: Dynamic IP from ISP (home/office internet). Solution:
  • Option A: Update IP each time it changes
  • Option B: Use API key auth with “Allow any IP”
  • Option C: Use VPN with static IP

​
Wrong Client Authorized

Symptom: Wrong server can access route. Solution:
  1. Review Environment Clients for route
  2. Remove unauthorized clients
  3. Only keep necessary clients assigned

​
Quick Reference

TaskSteps
Create clientResources → Clients → Create
Edit clientClients → Click name → Edit
Delete clientClients → Click name → Delete
Assign to routeRoute → Environment Clients → Assign
Disable clientEdit → Toggle Enabled OFF
Check current IPcurl https://api.ipify.org

​
Next Steps

What are Clients?

Understand IP whitelisting basics

Client Types

Server vs User vs Network (coming soon)

CIDR Notation

Understanding IP ranges (coming soon)

IP Authorization Issues

Fix common IP problems
Pro Tip: For production, always use Server type with static IPs. For development, use User type or API key auth to handle dynamic IPs easily.