Skip to main content

​
Quick Start Guide

Welcome to KnoxCall! This guide walks you through the same steps as our in-app QuickStart wizard. You’ll learn the three core concepts of KnoxCall: Clients, Routes, and Secrets.

​
What is KnoxCall?

KnoxCall is a webhook routing and proxy system that sits between your clients and your backend APIs. It provides:
  • 🔐 Security: API keys, IP whitelisting, request signing, encrypted secrets
  • 📊 Monitoring: Real-time logs, analytics, geo-tracking, alerts
  • 🔧 Flexibility: Environment switching, secret injection, rate limiting
  • 🌍 Compliance: VPN egress routing for data sovereignty (HIPAA, GDPR)

​
The Three Core Concepts

Before you start, understand these three foundational concepts:

​
1. Clients = IP Addresses (Authorization)

Clients are authorized IP addresses that can call your routes. They provide network-level security. Think of it as: “Which servers/devices are allowed to make requests?” Examples:
  • Your production server: 52.123.45.67
  • Your office network: 192.168.1.0/24
  • Your development laptop: 203.45.67.89

​
2. Routes = API Proxies (Forwarding Rules)

Routes define how incoming requests are forwarded to your backend APIs. Think of it as: “Where should KnoxCall send this request?” Example flow: 
Client → KnoxCall Route → Your Backend API

​
3. Secrets = Encrypted Credentials (Security)

Secrets store API keys, tokens, and passwords encrypted on KnoxCall’s servers. They’re injected into requests server-side so clients never see them. Think of it as: “How do I pass API keys to my backend without exposing them?”

​
Step 1: Create Your First Client

Let’s add your IP address as an authorized client.

​
1.1: Find Your IP Address

First, determine your current IP: 
curl https://api.ipify.org
Copy this IP address (e.g., 203.45.67.89)

​
1.2: Navigate to Clients

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

​
1.3: Fill in Client Details

Client Name: 
My Development Machine
Type: Select User For development laptops/workstations IP Address: 
203.45.67.89
Paste your IP from step 1.1 Description (optional): 
My laptop for testing KnoxCall
Enabled: ✓ ON

​
1.4: Save

Click Create Client Your IP is now whitelisted and ready to make requests! ✅
Production Tip: For production servers, use Server type and static IP addresses (like AWS Elastic IPs). For development, User type is fine for dynamic IPs.

​
Step 2: Create Your First Route

Now let’s create a route to forward requests to a backend API.

​
2.1: Navigate to Routes

  1. Click Resources in the sidebar
  2. Select Routes
  3. Click Create Route button

​
2.2: Configure Basic Settings

Route Name: 
test-api
Lowercase with hyphens. You’ll use this in requests. Target Base URL: 
https://jsonplaceholder.typicode.com
We’ll use a public test API for this tutorial Base Environment: 
production
This is your default environment (already exists) Enabled: ✓ ON

​
2.3: Security Settings

Leave defaults for now:
  • Requires Clients: ✓ ON (IP whitelist enabled)
  • Require Signature: OFF
  • Rate Limiting: OFF
We’ll configure advanced security later.

​
2.4: Save

Click Create Route Your route is now live! 🚀

​
2.5: Assign Your Client to the Route

Now connect your client (IP address) to your route:
  1. Find your route in the list
  2. Click on “test-api”
  3. Go to Environment Clients tab
  4. Select “production” environment
  5. Click Assign Clients
  6. Check “My Development Machine”
  7. Click Save
Your IP can now access this route! ✅

​
Step 3: Create Your First Secret

Let’s store a secret that can be injected into requests.

​
3.1: Navigate to Secrets

  1. Click Resources in the sidebar
  2. Select Secrets
  3. Click Create Secret button

​
3.2: Choose Secret Type

Select String Secret For API keys, tokens, passwords

​
3.3: Fill in Secret Details

Secret Name: 
test_api_key
Lowercase with underscores Secret Value: 
my-secret-api-key-12345
For this tutorial, use any test value Description (optional): 
Test API key for tutorial

​
3.4: Save

Click Create Secret Your secret is now encrypted and stored! 🔐
The secret value is encrypted immediately. You won’t be able to see the plaintext again in the UI!

​
Step 4: Make Your First Request

Now let’s test everything together!

​
4.1: Get Your API Key

You need a KnoxCall API key for authentication:
  1. Navigate to Settings in the sidebar
  2. Scroll to API Keys section
  3. Click Generate New Key
  4. Copy the key immediately (you’ll only see it once!)
Your API key looks like: tk_abc123_xyz789... (72 characters)

​
4.2: Get Your Tenant Subdomain

When you created your account, KnoxCall generated a unique subdomain: 
https://{hash}.{your-slug}.knoxcall.com
Example: https://a1b2c3d4.DunderMifflin.knoxcall.com Find yours in the admin UI header or your welcome email.

​
4.3: Make a Request

Now make your first proxied API call: 
curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
  -H "x-knoxcall-key: tk_abc123_xyz789..." \
  -H "x-knoxcall-route: test-api"
Replace:
  • a1b2c3d4.DunderMifflin.knoxcall.com → Your subdomain
  • tk_abc123_xyz789... → Your API key
  • test-api → Your route name

​
4.4: Expected Response

You should see JSON data from the test API: 
{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident...",
  "body": "quia et suscipit..."
}
Congratulations! You just made your first request through KnoxCall! 🎉

​
Understanding What Happened

Here’s the complete request flow: 
1. Your Request
   ↓
   GET https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1
   Headers:
     x-knoxcall-key: tk_abc123...      (Authentication)
     x-knoxcall-route: test-api        (Route selection)
   ↓
2. KnoxCall Receives Request
   ↓
   - Validates API key ✓
   - Loads route "test-api" ✓
   - Checks IP authorization (your client) ✓
   - Builds target URL: https://jsonplaceholder.typicode.com/posts/1
   ↓
3. KnoxCall Forwards Request
   ↓
   GET https://jsonplaceholder.typicode.com/posts/1
   ↓
4. Backend Responds
   ↓
   { "userId": 1, "id": 1, ... }
   ↓
5. KnoxCall Returns Response to You
   ↓
6. Request Logged in KnoxCall Dashboard

​
Step 5: View Your Request Logs

See your request in real-time:
  1. Navigate to Logs → API Logs
  2. Find your request (should be at the top)
  3. Click to expand and see:
    • Timestamp
    • HTTP method and full URL path
    • Status code (should be 200)
    • Response time
    • Request headers and body
    • Response headers and body
    • Source IP and geo-location
Real-time monitoring out of the box! 📊

​
What You’ve Learned

✅ Clients - You created an authorized IP address ✅ Routes - You created a forwarding rule to a backend API ✅ Secrets - You created an encrypted credential ✅ API Keys - You generated authentication for requests ✅ Requests - You made your first proxied API call ✅ Logs - You viewed request details in real-time

​
Next Steps: Level Up

Now that you understand the basics, explore advanced features:

Inject Secrets

Add secrets to route headers/body

Use Environments

Set up dev, staging, production

Rate Limiting

Protect your APIs from abuse

Request Signing

Add HMAC signatures for security

Analytics

View traffic metrics and trends

Alerts

Get notified of failures

​
Common Issues & Solutions

​
”Route not found”

Check:
  • You’re using the correct subdomain (with hash prefix)
  • The x-knoxcall-route header matches your route name exactly (case-sensitive)
  • The route is enabled in the UI

​
”Invalid API key”

Check:
  • You copied the full 72-character API key
  • The key hasn’t been deleted
  • You’re using the correct tenant subdomain

​
”IP not authorized”

This is the most common issue for new users! Causes:
  1. Your IP isn’t whitelisted as a client
  2. Client not assigned to the route environment
  3. Client is disabled
  4. Your IP changed (home networks, mobile)
Fix:
  1. Check your current IP: curl https://api.ipify.org
  2. Verify it matches your client IP in Clients page
  3. Make sure client is assigned to route → Environment Clients tab → “production”
  4. Check client is enabled
Quick test: Temporarily disable requires_clients on your route to test if IP authorization is the issue.

​
”502 Bad Gateway”

Causes:
  • Target URL is unreachable from the internet
  • Backend server is down
  • DNS resolution failed
Debug:
  • Test target URL directly: curl https://jsonplaceholder.typicode.com/posts/1
  • Check backend server is running
  • Verify target URL in route settings

​
Pro Tips

​
Tip 1: Use Test API Keys for Development

Create separate API keys for dev/staging/prod. Test keys can skip IP authorization for easier development.

​
Tip 2: Name Things Descriptively

Good names: 
production_server_1
office_network
stripe_prod_key
user_api_route
Bad names: 
client1
key
route
secret

​
Tip 3: Start Simple, Add Security Later

  1. First: Get basic route working
  2. Then: Add IP authorization
  3. Then: Add secrets
  4. Then: Add rate limiting
  5. Finally: Add request signing
Don’t try to configure everything at once!

​
Tip 4: Use the Support Chat

See that chat bubble in the bottom-right? That’s powered by Chatwoot and monitored by our team. Ask questions anytime!

​
Need Help?

  • 💬 Support chat (bottom right corner) - fastest way to get help
  • 📖 Full documentation - browse all guides and references
  • 📧 Email - [email protected] for account issues
  • 🐛 Bug reports - GitHub issues for technical problems

​
Summary: The KnoxCall Workflow

1. Create Clients (IP whitelist)
     ↓
2. Create Routes (forwarding rules)
     ↓
3. Create Secrets (encrypted credentials)
     ↓
4. Assign clients to routes
     ↓
5. (Optional) Inject secrets into routes
     ↓
6. Generate API key
     ↓
7. Make requests with:
   - x-knoxcall-key (API key)
   - x-knoxcall-route (route name)
     ↓
8. Monitor in real-time logs
You’re now ready to use KnoxCall! 🚀

📊 Statistics

  • Level: beginner
  • Time: 15 minutes
  • Prerequisites: None

🏷️ Tags

quickstart, beginner, tutorial, getting-started, wizard