> ## 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.
# Managing Clients
> Learn how to create, edit, delete, and assign clients in KnoxCall. Complete guide to client lifecycle management.
# 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:**
```text theme={"dark"}
production-api-server-1
staging-server-aws
john-dev-laptop
office-network-main
partner-acme-webhook-server
```
**Bad examples:**
```text theme={"dark"}
client1 (not descriptive)
server (too generic)
test (what is this?)
```
#### Type (Required)
Choose the appropriate type:
| Type | Best For | Example |
| ---------- | -------------------------------------------------- | ----------------------------------------- |
| **Server** | Production servers, office networks, cloud subnets | AWS EC2 with Elastic IP, `192.168.1.0/24` |
| **User** | Developer machines, dynamic IPs | Laptops, home offices |
**Recommendation:** Use **Server** for production infrastructure, **User** for individual people. Both types support single IPs and CIDR ranges.
#### IP Address (Required)
Enter the IP address or CIDR range.
**Single IP:**
```text theme={"dark"}
52.123.45.67
```
**IP Range (CIDR):**
```text theme={"dark"}
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:**
```bash theme={"dark"}
curl https://api.ipify.org
```
#### Description (Optional but Recommended)
Document what this client is for.
**Good descriptions:**
```text theme={"dark"}
"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 **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 → **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:**
```text theme={"dark"}
IP: 203.45.67.89
```
**After:**
```text theme={"dark"}
IP: 203.45.67.100
```
**How to check current IP:**
```bash theme={"dark"}
curl https://api.ipify.org
```
#### Expand IP Range
**When:** Need to cover more IPs
**Before:**
```text theme={"dark"}
IP: 192.168.1.0/24 (covers .0 to .255)
```
**After:**
```text theme={"dark"}
IP: 192.168.0.0/16 (covers .0.0 to .255.255)
```
#### Change Type
**When:** Server gets static IP
**Before:**
```text theme={"dark"}
Type: User
IP: 203.45.67.89 (dynamic)
```
**After:**
```text theme={"dark"}
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 → **Clients** tab
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:
```bash theme={"dark"}
for ip in $(cat ip_list.txt); do
curl -X POST https://knoxcall.com/admin/clients \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-d "{\"name\": \"server-$ip\", \"ip_address\": \"$ip\", \"type\": \"server\"}"
done
```
***
## Client Organization
### Naming Convention
Use consistent naming for easy management:
**Pattern:** `{environment}-{purpose}-{identifier}`
**Examples:**
```text theme={"dark"}
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:
```text theme={"dark"}
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: Server
* 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** → **Tenant** tab → **API Keys**
2. Enable **"Allow any IP"** for dev/test keys
3. Use key in requests instead of IP whitelisting
**Request with API key:**
```bash theme={"dark"}
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 → **Clients** tab
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 **Clients** tab for route
2. Remove unauthorized clients
3. Only keep necessary clients assigned
***
## Quick Reference
| Task | Steps |
| -------------------- | ----------------------------- |
| **Create client** | Resources → Clients → Create |
| **Edit client** | Clients → Click name → Edit |
| **Delete client** | Clients → Click name → Delete |
| **Assign to route** | Route → Clients tab → Assign |
| **Disable client** | Edit → Toggle Enabled OFF |
| **Check current IP** | `curl https://api.ipify.org` |
***
## Next Steps
Understand IP whitelisting basics
Server vs User types explained
Understanding IP ranges (coming soon)
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.