> ## 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.
# Creating Your First Route
> Create your first API route in KnoxCall. Learn how routes work and how to proxy requests to your backend.
# Creating Your First Route
Get your first webhook route up and running. A route forwards incoming requests from your clients to your backend API with added security and monitoring.
## What is a Route?
A **route** is a forwarding configuration that tells KnoxCall where to send incoming requests. Think of it as a smart proxy that:
* ✅ Validates API keys and IP addresses
* ✅ Injects secrets (API keys, OAuth tokens) into requests
* ✅ Logs all requests and responses
* ✅ Applies rate limiting
* ✅ Supports multiple environments (dev, staging, production)
## How Routes Work
Here's the request flow:
```text theme={"dark"}
Client Request
↓
POST https://a1b2c3d4.DunderMifflin.knoxcall.com/webhooks/order
Headers:
x-knoxcall-route: shopify-orders
x-knoxcall-key: tk_abc123... (for API key auth)
OR your IP is whitelisted (for IP-based auth)
↓
KnoxCall Route Selection:
- Subdomain identifies your TENANT (a1b2c3d4.DunderMifflin)
- x-knoxcall-route header selects the ROUTE ("shopify-orders")
↓
Validates API key OR IP address ✓
Checks client authorization ✓
Injects secrets: {{secret:shopify_api_key}}
↓
Forwards to: https://api.yourbackend.com/webhooks/order
↓
Response → Back to client
```
**Important**:
* **Subdomain** determines your tenant
* **`x-knoxcall-route` header** determines which route to use
* The URL path (`/webhooks/order`) is passed through to your backend unchanged
## Create Your First Route
### Step 1: Open Routes Page
1. Navigate to **Routes** in the sidebar
2. Click **Add Route**
### Step 2: Configure Basic Settings
**Route Name:**
```text theme={"dark"}
my-first-route
```
*Lowercase, use hyphens. This name is used in the `x-knoxcall-route` header to identify which route to use.*
**Target Base URL:**
```text theme={"dark"}
https://jsonplaceholder.typicode.com
```
*Your backend API's base URL. We'll use a test API for this example.*
**Base Environment:**
```text theme={"dark"}
production
```
*Default environment (already created for you)*
### Step 3: Security Settings (Optional for Now)
You can leave these as defaults:
* **Requires Clients**: ON (IP whitelist required)
* **Require Signature**: OFF
* **Rate Limiting**: OFF
We'll cover these in later guides.
### Step 4: Save
Click **Create Route** - your route is now live!
## Test Your Route
### Prerequisites
You need:
1. Your tenant subdomain (e.g., `a1b2c3d4.DunderMifflin.knoxcall.com`)
2. An API key (create one in Settings → Security tab → API Keys)
### Make a Request
**Option 1: Using API Key Authentication**
```bash theme={"dark"}
curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
-H "x-knoxcall-route: my-first-route" \
-H "x-knoxcall-key: tk_abc123_xyz789..."
```
**Option 2: Using IP-Based Authentication** (if your IP is whitelisted)
```bash theme={"dark"}
curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
-H "x-knoxcall-route: my-first-route"
```
**Required Headers:**
* `x-knoxcall-route`: The route name you created (REQUIRED)
* `x-knoxcall-key`: Your API key (if not using IP-based auth)
**URL Structure:**
* `https://a1b2c3d4.DunderMifflin.knoxcall.com` → Your unique tenant subdomain
* `/posts/1` → Path passed through to your backend
* Subdomain identifies your tenant, header identifies your route
### Expected Response
You should see JSON data from the test API:
```json theme={"dark"}
{
"userId": 1,
"id": 1,
"title": "sunt aut facere...",
"body": "quia et suscipit..."
}
```
This means your route is working! 🎉
## Understanding URL Mapping
KnoxCall forwards the entire path to your backend:
| Client Request | Target Base URL | Forwarded To |
| ------------------------- | ------------------------- | ---------------------------------------- |
| `/posts/1` | `https://api.example.com` | `https://api.example.com/posts/1` |
| `/api/v2/users` | `https://backend.com` | `https://backend.com/api/v2/users` |
| `/webhooks/stripe?id=123` | `https://app.com` | `https://app.com/webhooks/stripe?id=123` |
**Query parameters** are also passed through unchanged.
## View Request Logs
1. Navigate to **Logs** → **API Logs**
2. Find your request
3. Click to see full details:
* Request headers and body
* Response headers and body
* Response time
* Status code
* Source IP and geo-location
## Common Configuration Options
### Inject Headers
Add custom headers to every request:
```json theme={"dark"}
{
"X-API-Key": "{{secret:my_api_key}}",
"X-Custom-Header": "my-value"
}
```
Use `{{secret:name}}` to inject encrypted secrets from your vault.
### Inject Body Fields
Add fields to JSON request bodies:
```json theme={"dark"}
{
"api_key": "{{secret:printnode_key}}",
"metadata": {
"source": "knoxcall"
}
}
```
### Method-Specific Configuration
Configure different headers per HTTP method:
* **POST requests**: Inject write API key
* **GET requests**: Inject read-only API key
* **DELETE requests**: Require admin API key
This is configured in the **Method Configs** section.
## Security: Client IP Authorization
By default, `requires_clients: true` means only whitelisted IP addresses can use this route.
**To allow your IP:**
1. Navigate to **Clients**
2. Click **Add Client**
3. Enter:
* Name: "My Office"
* Type: "server"
* IP Address: Your IP (or CIDR range like `192.168.1.0/24`)
4. Save
5. Go back to your route → **Clients** tab
6. Assign the client to the "production" environment
Now requests from your IP will work!
**To disable IP authorization** (for testing):
* Edit your route
* Toggle **Requires Clients** to OFF
* Save
Disabling client IP authorization means anyone with your API key can call the route. Only do this for public routes.
## Common Issues
### "Route not found"
**Check:**
* The `x-knoxcall-route` header value matches your route name exactly (case-sensitive)
* The route is enabled (toggle in route list)
* You're using the correct tenant subdomain
### "IP not authorized"
**Fix:**
* Add your IP address as a client (see "Client IP Authorization" above)
* Or disable `requires_clients` temporarily for testing
### "Invalid API key"
**Check:**
* You copied the full API key (the complete `tk_..._...` string, not just the prefix shown in the dashboard)
* The key hasn't been deleted
* You're using the correct tenant subdomain
### "502 Bad Gateway"
**Causes:**
* Your target URL is unreachable from the internet
* The backend server is down
* DNS resolution failed for the target domain
**Debug:**
* Test the target URL directly: `curl https://your-backend.com/endpoint`
* Check your backend server logs
* Verify the target URL in route settings
### "Connection timeout"
**Causes:**
* Your backend is slow to respond (> 30 seconds default timeout)
* Network connectivity issues
* Backend server overloaded
**Fix:**
* Increase timeout in route settings
* Optimize your backend response time
* Check backend server resources
## Next Steps
Now that you have a working route:
Whitelist IP addresses with clients
Set up dev, staging, production
Add encrypted API keys to requests
Protect your backend from abuse
## Advanced Topics
* **[AI Route Setup](/advanced/ai-route-setup)**: Let AI configure routes from code or cURL commands
* **[Route Examples](/essentials/routes/route-examples)**: Real-world patterns for Stripe, Twilio, etc.
* **Request Signing**: HMAC-SHA256 signatures to prevent replay attacks
* **[Workflow Automation](/workflows/workflows-overview)**: Trigger workflows on route events
* **[Webhooks](/webhooks/webhooks-overview)**: Get notified of successes and failures
***
* **Level**: beginner
* **Time**: 5 minutes
`routes`, `quickstart`, `beginner`, `proxy`