​

Securing Your API Routes

​

Authentication Methods

​

1. OAuth 2.1 Access Tokens (Recommended)

• Internal services
• Server-to-server communication
• New integrations

1. Register an OAuth client under Settings → Security → OAuth Clients (on a developer machine, knoxcall login does this for you)
2. Mint a token via POST /oauth/token — or skip this step and let the SDK handle it
3. Clients send: Authorization: Bearer kc_… plus x-knoxcall-route: <route-slug>

​

2. JWT Tokens

• User-facing applications
• Mobile apps
• Web applications

1. Configure JWT settings in route
2. Set token expiration
3. Add public key for verification

​

3. Signature Verification

• Webhooks
• High-security applications
• Payment processing

1. Enable signature verification
2. Share signing secret with clients
3. Clients sign requests with HMAC-SHA256

​

IP Allowlisting

1. Navigate to route settings
2. Add allowed IPs:
   192.168.1.1
   10.0.0.0/8
   
3. Only these IPs can access the route

​

Rate Limiting

• Requests: Number of requests allowed
• Window: Time window (e.g., 60 seconds)
• Burst: Allow short bursts

• 100 requests per minute
• Burst: 120 requests

​

CORS Configuration

{
  "allowed_origins": ["https://your-app.com"],
  "allowed_methods": ["GET", "POST"],
  "allowed_headers": ["Content-Type", "Authorization"]
}

​

Security Best Practices

​

1. Use HTTPS Only

• Never send credentials over HTTP
• Enforce HTTPS in your application

​

2. Rotate Keys Regularly

• Prefer short-lived OAuth tokens (kc_…) — they expire after an hour, so there is nothing to rotate
• If you use long-lived API keys, rotate them every 90 days
• Update clients before expiration

​

3. Principle of Least Privilege

• Only grant necessary permissions
• Use different keys for different services

​

4. Monitor for Anomalies

• Set up alerts for unusual activity
• Watch for failed auth attempts
• Monitor for rate limit violations

​

5. Keep Secrets Secure

• Never commit secrets to git
• Use environment variables
• Rotate secrets immediately if compromised

​

Common Security Mistakes

• Hardcode API keys in frontend code
• Use same key for all environments
• Ignore rate limiting
• Skip signature verification for webhooks

• Store keys in backend environment variables
• Use different keys for dev/staging/prod
• Always enable rate limiting
• Verify webhook signatures

​

Audit Logs

1. Go to Audit Logs
2. Filter by event type
3. Look for suspicious activity