> ## 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.

# Quick Start Guide

> Get started with KnoxCall in minutes. Follow our QuickStart wizard to create your first client, route, and secret.

# 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 an **API gateway and reverse-proxy platform** 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:**

```text theme={"dark"}
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:

```bash theme={"dark"}
curl https://api.ipify.org
```

Copy this IP address (e.g., `203.45.67.89`)

### 1.2: Navigate to Clients

1. Expand **Proxy** in the sidebar
2. Select **Clients**
3. Click **Create Client** button

### 1.3: Fill in Client Details

**Client Name:**

```text theme={"dark"}
My Development Machine
```

**Type:** Select **User**
*For development laptops/workstations*

**IP Address:**

```text theme={"dark"}
203.45.67.89
```

*Paste your IP from step 1.1*

**Description** (optional):

```text theme={"dark"}
My laptop for testing KnoxCall
```

**Enabled:** ✓ ON

### 1.4: Save

Click **Create Client**

Your IP is now whitelisted and ready to make requests! ✅

<Note>
  **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.
</Note>

## 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. Expand **Proxy** in the sidebar
2. Select **Routes**
3. Click **Create Route** button

### 2.2: Configure Basic Settings

**Route Name:**

```text theme={"dark"}
test-api
```

*Lowercase with hyphens. You'll use this in requests.*

**Target Base URL:**

```text theme={"dark"}
https://jsonplaceholder.typicode.com
```

*We'll use a public test API for this tutorial*

**Base Environment:**

```text theme={"dark"}
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 **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. Expand **Protect** 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:**

```text theme={"dark"}
test_api_key
```

*Lowercase with underscores*

**Secret Value:**

```text theme={"dark"}
my-secret-api-key-12345
```

*For this tutorial, use any test value*

### 3.4: Save

Click **Create Secret**

Your secret is now encrypted and stored! 🔐

<Warning>
  The secret value is encrypted immediately. You won't be able to see the plaintext again in the UI!
</Warning>

## 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** (gear icon at bottom of sidebar)
2. Click the **Security** tab
3. Scroll to the **API Keys** section
4. Click **Add API Key**
5. **Copy the key immediately** (you'll only see it once!)

Your API key looks like: `tk_abc123_xyz789...`

### 4.2: Get Your Tenant Subdomain

When you created your account, KnoxCall generated a unique subdomain:

```text theme={"dark"}
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:

```bash theme={"dark"}
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:

```json theme={"dark"}
{
  "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:

```text theme={"dark"}
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:

<CardGroup cols={2}>
  <Card title="Inject Secrets" icon="key" href="/getting-started/first-secret">
    Add secrets to route headers/body
  </Card>

  <Card title="Use Environments" icon="layer-group" href="/getting-started/first-environment">
    Set up dev, staging, production
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/advanced/rate-limiting">
    Protect your APIs from abuse
  </Card>

  <Card title="Request Signing" icon="signature" href="/security/request-signing">
    Add HMAC signatures for security
  </Card>

  <Card title="Analytics" icon="chart-line" href="/monitoring/analytics">
    View traffic metrics and trends
  </Card>

  <Card title="Alerts" icon="bell" href="/monitoring/alerts">
    Get notified of failures
  </Card>
</CardGroup>

## 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 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 → **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:**

```text theme={"dark"}
production_server_1
office_network
stripe_prod_key
user_api_route
```

**Bad names:**

```text theme={"dark"}
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** - [support@knoxcall.com](mailto:support@knoxcall.com) for account issues
* 🐛 **Bug reports** - GitHub issues for technical problems

## Summary: The KnoxCall Workflow

```text theme={"dark"}
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!** 🚀

***

<CardGroup cols={2}>
  <Card title="📊 Statistics" icon="chart-line">
    * **Level**: beginner
    * **Time**: 15 minutes
    * **Prerequisites**: None
  </Card>

  <Card title="🏷️ Tags" icon="tags">
    `quickstart`, `beginner`, `tutorial`, `getting-started`, `wizard`
  </Card>
</CardGroup>