Skip to main content

​
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

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

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: 
https://YOUR-SUBDOMAIN.knoxcall.com/users/123
KnoxCall forwards to: 
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

// ❌ 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

// ✅ 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: 
┌─────────────────────────────────────────────────────────┐
│                     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

Name: production_app_server
IP: 52.123.45.67 (your app backend server)
Type: Server

​
Step 2: Create a Secret

Name: stripe_prod_key
Value: sk_live_abc123xyz789... (encrypted)

​
Step 3: Create a Route

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

ConceptPurposeExample
ClientWho can access52.123.45.67 (your server’s IP)
RouteWhere to forwardstripe-payments → https://api.stripe.com
SecretCredentials to injectstripe_prod_key = sk_live_abc123...

​
Next Steps

Now that you understand the core concepts, you’re ready to start building:

Quick Start Guide

Follow the step-by-step tutorial

Create Your First Route

Set up your first API route

Create Your First Client

Authorize an IP address

Create Your First Secret

Store credentials securely

Route Examples

See real-world route patterns

AI Route Setup

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: 
{
  "Authorization": "Bearer {{secret:stripe_key}}",
  "X-API-Key": "{{secret:sendgrid_key}}"
}

​
What if my IP changes frequently?

Use Dynamic IP client type, which allows you to use API key authentication instead of IP whitelisting. Perfect for development machines with dynamic IPs.
Remember: Clients = Who, Routes = Where, Secrets = How. Master these three, and you’ve mastered KnoxCall!