> ## 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.
# Core Concepts
> Understand the three foundational concepts of KnoxCall: Clients, Routes, and Secrets
# Core Concepts
Before diving into KnoxCall, it's essential to understand the three foundational concepts that power the platform:
1. **Clients** - Who can access your routes
2. **Routes** - Where requests go
3. **Secrets** - How credentials are managed securely
Think of these as the building blocks of your API routing infrastructure.
***
## 1. Clients = Authorization (Who Can Access)
**Clients** are authorized IP addresses or API keys that can call your routes.
### What is a Client?
A client represents a **trusted source** that's allowed to make requests through KnoxCall. This can be:
* Your production server's IP address
* Your office network IP range
* Your development machine
* A partner's API server
* A mobile app backend
### Why Use Clients?
Clients provide **network-level security**:
✅ Only whitelisted IPs can access your routes
✅ Block unauthorized access automatically
✅ Track which systems are making requests
✅ Different clients for dev, staging, and production
### Simple Example
```text theme={"dark"}
Your Server (52.123.45.67) → Allowed ✅
Random Internet User → Blocked ❌
```
### Key Concept
**IP Whitelisting**: KnoxCall checks every incoming request's IP address. If it's not on your authorized client list, the request is rejected before it even reaches your route.
***
## 2. Routes = Forwarding Rules (Where Requests Go)
**Routes** define how incoming requests are forwarded to your backend APIs.
### What is a Route?
A route is a **smart proxy** that sits between your clients and your backend services. It:
* Receives requests from authorized clients
* Applies security rules and transformations
* Forwards to your backend API
* Returns the response
### The Flow
```text theme={"dark"}
Client Request
↓
KnoxCall Route (validates, transforms, logs)
↓
Your Backend API
↓
Response back to client
```
### Why Use Routes?
Routes solve common API problems:
✅ **Hide backend URLs** - Clients never know your real endpoints
✅ **Centralize credentials** - API keys injected server-side
✅ **Monitor everything** - All requests logged automatically
✅ **Add security layers** - Rate limiting, IP checks, signatures
✅ **Manage environments** - Dev, staging, prod with one route
### Simple Example
**Route name**: `user-api`
**Target**: `https://api.example.com`
**Methods**: GET, POST
When client calls:
```text theme={"dark"}
https://YOUR-SUBDOMAIN.knoxcall.com/users/123
```
KnoxCall forwards to:
```text theme={"dark"}
https://api.example.com/users/123
```
***
## 3. Secrets = Encrypted Credentials (How Secrets Are Managed)
**Secrets** are encrypted credentials (API keys, passwords, tokens) that KnoxCall injects into your requests **server-side**.
### What is a Secret?
A secret is a **secure vault entry** containing sensitive data that:
* Is encrypted with AES-256-GCM
* Never exposed to clients
* Injected into requests automatically
* Can be rotated without code changes
### Why Use Secrets?
Secrets prevent **credential exposure**:
✅ **Never in client code** - API keys stay on KnoxCall's servers
✅ **Encrypted storage** - Military-grade encryption
✅ **Easy rotation** - Update once, affects all routes
✅ **Audit trail** - Track when secrets are used
### The Problem Without Secrets
```javascript theme={"dark"}
// ❌ BAD: API key exposed in frontend
fetch("https://api.stripe.com/charges", {
headers: { "Authorization": "Bearer sk_live_abc123..." }
});
```
Anyone with browser dev tools can see your Stripe key!
### The Solution With Secrets
```javascript theme={"dark"}
// ✅ GOOD: No secrets exposed
fetch("https://YOUR-SUBDOMAIN.knoxcall.com/api/payments", {
headers: { "x-knoxcall-route": "stripe-payments" }
});
```
KnoxCall injects your Stripe key **server-side**. The client never sees it!
### How It Works
1. Store secret in KnoxCall: `stripe_prod_key = sk_live_abc123...`
2. Reference in route config: `{{secret:stripe_prod_key}}`
3. KnoxCall decrypts and injects automatically
4. Backend receives real API key
5. Client never sees plaintext value
***
## How They Work Together
These three concepts work in harmony to secure and route your API traffic:
```text theme={"dark"}
┌─────────────────────────────────────────────────────────┐
│ 1. CLIENT │
│ (Authorized IP: 52.123.45.67) │
│ │
│ Makes request with x-knoxcall-route: user-api │
└─────────────────────┬───────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 2. KNOXCALL ROUTE │
│ (user-api) │
│ │
│ • Validates client IP ✓ │
│ • Loads route configuration ✓ │
│ • Decrypts secrets ✓ │
│ • Injects credentials into headers ✓ │
│ • Logs request ✓ │
│ • Forwards to backend ✓ │
└─────────────────────┬───────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 3. YOUR BACKEND API │
│ (https://api.example.com) │
│ │
│ Receives request with: │
│ • Real API credentials (from secrets) │
│ • All original request data │
│ • No knowledge of KnoxCall │
└─────────────────────────────────────────────────────────┘
```
***
## Real-World Example
Let's see how all three work together in a real scenario:
### Scenario: Mobile App Calling Stripe API
**Goal**: Your mobile app needs to charge customers via Stripe, but you can't embed the Stripe API key in the app (users could extract it).
**Solution with KnoxCall**:
### Step 1: Create a Client
```text theme={"dark"}
Name: production_app_server
IP: 52.123.45.67 (your app backend server)
Type: Server
```
### Step 2: Create a Secret
```text theme={"dark"}
Name: stripe_prod_key
Value: sk_live_abc123xyz789... (encrypted)
```
### Step 3: Create a Route
```text theme={"dark"}
Name: stripe-payments
Target: https://api.stripe.com
Header Injection:
Authorization: Bearer {{secret:stripe_prod_key}}
Requires Clients: ✓
```
### Step 4: Assign Client to Route
Connect "production\_app\_server" to "stripe-payments" route.
### Step 5: Make Request
Your app backend calls your proxy subdomain. The path after the
subdomain is forwarded **verbatim** to the route's target — here
`/v1/charges` is appended to `https://api.stripe.com`, so Stripe
receives `https://api.stripe.com/v1/charges`. (This `/v1` is Stripe's
path, not KnoxCall's own `/v1` platform API prefix.)
```bash theme={"dark"}
curl https://YOUR-SUBDOMAIN.knoxcall.com/v1/charges \
-H "x-knoxcall-route: stripe-payments" \
-H "x-knoxcall-key: YOUR_KNOXCALL_API_KEY" \
-d "amount=1000" \
-d "currency=usd"
```
### What Happens
1. **Client Check**: KnoxCall sees request from 52.123.45.67 → Authorized ✅
2. **Route Lookup**: Loads "stripe-payments" route config
3. **Secret Injection**: Decrypts `stripe_prod_key` and adds to headers
4. **Forward**: Sends to Stripe with real API key
5. **Response**: Returns Stripe's response to your app
6. **Logging**: Records everything in audit logs
**Result**: Your Stripe API key is never exposed to your mobile app or clients!
***
## Quick Comparison
| Concept | Purpose | Example |
| ---------- | --------------------- | -------------------------------------------- |
| **Client** | Who can access | `52.123.45.67` (your server's IP) |
| **Route** | Where to forward | `stripe-payments` → `https://api.stripe.com` |
| **Secret** | Credentials to inject | `stripe_prod_key` = `sk_live_abc123...` |
***
## Next Steps
Now that you understand the core concepts, you're ready to start building:
Follow the step-by-step tutorial
Set up your first API route
Authorize an IP address
Store credentials securely
See real-world route patterns
Let AI configure routes for you
***
## Common Questions
### Do I need all three?
**For basic usage**: You need at least a **Route**. Clients and Secrets are optional but highly recommended for security.
**For production**: You should use all three for maximum security and flexibility.
### Can I have multiple clients per route?
**Yes!** You can assign multiple clients to a single route. For example, both your production server and staging server can access the same route.
### Can I use multiple secrets in one route?
**Yes!** You can inject multiple secrets into headers and body. For example:
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:stripe_key}}",
"X-API-Key": "{{secret:sendgrid_key}}"
}
```
### What if my IP changes frequently?
Both client types (**User** and **Server**) are IP-allowlist identities — each client is pinned to one or more IP addresses, so a changing IP would normally be rejected. For development machines where the IP changes regularly, use a **test API key**, which skips the client IP check entirely. (API keys are managed separately and are not tied to a client type.)
***
**Remember**: Clients = Who, Routes = Where, Secrets = How. Master these three, and you've mastered KnoxCall!