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:

Client Request
    ↓
    POST https://a1b2c3d4.DunderMifflin.knoxcall.com/webhooks/order
    Headers:
      x-knoxcall-route: shopify-orders
      Authorization: Bearer kc_...  (OAuth token 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 access token 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

Navigate to Routes in the sidebar
Click Add Route

Step 2: Configure Basic Settings

Route Name:

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:

https://jsonplaceholder.typicode.com

Your backend API’s base URL. We’ll use a test API for this example. Base Environment:

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:

Your tenant subdomain (e.g., a1b2c3d4.DunderMifflin.knoxcall.com) — the SDK discovers this automatically
To be signed in: run knoxcall login once (or create an OAuth client under Settings → API → OAuth Clients and set KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET)

Make a Request

Option 1: Using the SDK (recommended)

import { KnoxCall } from "@knoxcall/sdk";

const client = new KnoxCall(); // credentials from `knoxcall login`
const resp = await client.call("my-first-route", { path: "/posts/1" });
console.log(await resp.json());

Option 2: Using curl with an OAuth token

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
  -H "x-knoxcall-route: my-first-route" \
  -H "Authorization: Bearer $TOKEN"

Option 3: Using IP-Based Authentication (if your IP is whitelisted)

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)
Authorization: Bearer <token>: Your OAuth token (if not using IP-based auth). Legacy API keys go in x-knoxcall-key instead — never as a Bearer header on the proxy.

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:

{
  "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

Navigate to Logs → API Logs
Find your request
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:

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

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

On your route, open the Clients tab and click Add Client
Pick an existing client from the list — or click New client (it is the first row, and the only button when you have no clients yet)
On the client form, enter:
- Name: “My Office”
- Type: “server”
- IP Address: Your IP (or CIDR range like 192.168.1.0/24)
Click Create Client — you are taken straight back to your route with the new client selected

Now requests from your IP will work!

Your route form is kept while you create the client. The same goes for a new client or environment form: leave the page and come back, and what you had typed is restored (with a Discard draft link if you would rather start again). Drafts live only in the current browser tab and are dropped when it closes. A draft never keeps a credential: a header value typed in the clear (rather than as a {{secret:...}} reference) and anything in the target URL’s query string are dropped, and the restored form tells you what to enter again.

To disable IP authorization (for testing):

Edit your route
Toggle Requires Clients to OFF
Save

Disabling client IP authorization means anyone with a valid credential (OAuth token or API key) can call the route. Only do this for public routes.

Common Issues

”Route not found”

With a valid credential for your workspace, a Route that does not resolve answers 404 with a JSON envelope naming the reason — route_not_found (the identifier you sent is echoed back), environment_not_configured or environment_disabled (the environment is named) — and X-Knox-Origin: knoxcall with no X-Knox-Upstream-Status, so you can tell it from your provider’s own 404s. Without a valid credential the same request answers the opaque 401 Unauthorized below, on purpose: route names are not enumerable by anyone your workspace has not authenticated. Check:

The x-knoxcall-route header value matches your route’s slug, name or UUID exactly (case-sensitive)
The route is enabled (toggle in route list), and the environment you named (or your default environment) is configured and enabled on it
You’re using the correct tenant subdomain — and, if you got a 401 rather than a 404, that your credential belongs to this workspace

”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” / authentication errors

Check:

Your OAuth token hasn’t expired (tokens last 1 hour — the SDK refreshes automatically; re-mint for curl)
Legacy keys only: you copied the full key (the complete tk_..._... string, not just the prefix shown in the dashboard) and it 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:

Add IP Security

Whitelist IP addresses with clients

Use Environments

Set up dev, staging, production

Inject Secrets

Add encrypted API keys to requests

Rate Limiting

Protect your backend from abuse

Advanced Topics

AI Route Setup: Let AI configure routes from code or cURL commands
Route Examples: Real-world patterns for Stripe, Twilio, etc.
Request Signing: HMAC-SHA256 signatures to prevent replay attacks
Workflow Automation: Trigger workflows on route events
Webhooks: Get notified of successes and failures

📊 Statistics

Level: beginner
Time: 5 minutes

🏷️ Tags

routes, quickstart, beginner, proxy

​Creating Your First Route

​What is a Route?

​How Routes Work

​Create Your First Route

​Step 1: Open Routes Page

​Step 2: Configure Basic Settings

​Step 3: Security Settings (Optional for Now)

​Step 4: Save

​Test Your Route

​Prerequisites

​Make a Request

​Expected Response

​Understanding URL Mapping

​View Request Logs

​Common Configuration Options

​Inject Headers

​Inject Body Fields

​Method-Specific Configuration

​Security: Client IP Authorization

​Common Issues

​”Route not found”

​”IP not authorized”

​”Invalid API key” / authentication errors

​”502 Bad Gateway”

​”Connection timeout”

​Next Steps

Add IP Security

Use Environments

Inject Secrets

Rate Limiting

​Advanced Topics

📊 Statistics

🏷️ Tags

Creating Your First Route

What is a Route?

How Routes Work

Create Your First Route

Step 1: Open Routes Page

Step 2: Configure Basic Settings

Step 3: Security Settings (Optional for Now)

Step 4: Save

Test Your Route

Prerequisites

Make a Request

Expected Response

Understanding URL Mapping

View Request Logs

Common Configuration Options

Inject Headers

Inject Body Fields

Method-Specific Configuration

Security: Client IP Authorization

Common Issues

”Route not found”

”IP not authorized”

”Invalid API key” / authentication errors

”502 Bad Gateway”

”Connection timeout”

Next Steps

Advanced Topics