​

Rotation Strategies

​

What Can Be Rotated?

• 🌐 Subdomain Hash: Regenerate your tenant’s unique subdomain URL
• 🔑 API Keys: Create new keys, revoke old ones
• 🔐 Secrets: Add new versions of encrypted credentials
• 🛣️ Routes: Duplicate route configurations
• 🌍 Environments: Clone environment overrides

​

Why Rotate?

​

Security Best Practices

• ✅ Credentials are compromised or suspected compromise
• ✅ Employee leaves or loses access
• ✅ Compliance requirements (e.g., 90-day rotation)
• ✅ Moving from development to production
• ✅ Deprecating old integration

• 🔒 Limit window of exposure from leaked credentials
• 📊 Audit trail of when credentials changed
• 🎯 Zero-trust architecture (regular rotation = no long-lived secrets)
• 🛡️ Compliance with security frameworks (SOC 2, ISO 27001)

​

Rotation Strategy 1: Subdomain Hash

​

What It Is

https://{hash}.{slug}.knoxcall.com

​

When to Roll

• 🚨 Subdomain leaked publicly (e.g., hardcoded in open-source repo)
• 🔒 Maximum security required (prevents URL-based attacks)
• 🏢 Transferring tenant ownership

• ⚠️ Active integrations depend on the URL
• ⚠️ No security incident occurred

​

How to Roll Subdomain Hash

​

Step 1: Document All Integrations

• Production server API calls (EC2 instance)
• Staging server API calls
• Development laptops
• Mobile app config
• CI/CD pipelines
• Monitoring tools (Datadog, New Relic)
• Documentation/wiki pages

​

Step 2: Navigate to Profile

1. Go to Settings (gear icon in sidebar)
2. Scroll to Base URL section
3. Current subdomain is displayed:
   Copy

   https://a1b2c3d4.DunderMifflin.knoxcall.com
   

​

Step 3: Click “Roll Base URL”

WARNING: Rolling the Base URL will generate a new subdomain hash.
This will immediately break all existing API calls using the old URL.
Clients will need to update to the new URL.
This action cannot be undone.
Are you absolutely sure?

FINAL WARNING: Once you roll the Base URL, the old subdomain hash
will be permanently lost and cannot be recovered.
All active integrations will stop working until updated.
Continue?

​

Step 4: Update All Clients

Old: https://a1b2c3d4.DunderMifflin.knoxcall.com
New: https://x9y8z7w6.DunderMifflin.knoxcall.com

// Before
const API_URL = "https://a1b2c3d4.DunderMifflin.knoxcall.com";

// After
const API_URL = "https://x9y8z7w6.DunderMifflin.knoxcall.com";

​

Step 5: Verify

curl -X GET "https://x9y8z7w6.DunderMifflin.knoxcall.com/api/test" \
  -H "x-knoxcall-key: YOUR_API_KEY" \
  -H "x-knoxcall-route: test-route"

​

Zero-Downtime Subdomain Rotation

// ❌ Hardcoded
const url = "https://a1b2c3d4.DunderMifflin.knoxcall.com";

// ✅ Environment variable
const url = process.env.KNOXCALL_BASE_URL;

# Staging first
export KNOXCALL_BASE_URL="https://x9y8z7w6.DunderMifflin.knoxcall.com"

# Test staging
curl https://staging.example.com/health

# Production (after staging verified)
export KNOXCALL_BASE_URL="https://x9y8z7w6.DunderMifflin.knoxcall.com"

# Instance 1
systemctl restart app-instance-1
# Verify
# Instance 2
systemctl restart app-instance-2
# Continue...

​

Rotation Strategy 2: API Keys

​

What It Is

x-knoxcall-key: tk_abc123xyz789...

​

When to Rotate

• ✅ Every 90 days (security best practice)
• ✅ Key exposed (logs, screenshots, public repo)
• ✅ Employee departure
• ✅ Service migration (dev → prod)
• ✅ Suspect unauthorized access

• Limit blast radius of compromised keys
• Clear audit trail of which key made which requests
• Different keys per environment (dev/staging/prod)

​

How to Rotate API Keys

​

Method 1: Create-Before-Revoke (Zero Downtime)

1. Navigate to Settings → Profile
2. Scroll to API Keys section
3. Click + Create API Key
4. Name it (e.g., “Production Key 2025 Q1”)
5. Copy the key immediately (you’ll only see it once!)

// Old key
const API_KEY = "tk_abc123xyz789...";

// New key
const API_KEY = "tk_def456ghi789...";

Key ID: key_def456... ✓

• Production servers
• Staging servers
• Development environments
• CI/CD pipelines

-- Check if old key still in use
SELECT COUNT(*) FROM api_logs
WHERE key_id = 'key_abc123...'
AND timestamp > NOW() - INTERVAL '1 day';

1. Navigate to Settings → Profile → API Keys
2. Find old key: tk_abc123...
3. Click Revoke
4. Confirm

​

Method 2: Blue-Green Key Rotation

• Blue Key: tk_blue_abc123... (currently active)
• Green Key: tk_green_def456... (standby)

Week 1: Blue active, create new Green
Week 2: Switch to Green, revoke old Blue
Week 3: Green active, create new Blue
Week 4: Switch to Blue, revoke old Green
...cycle continues

• Always have backup key ready
• Predictable rotation schedule
• Easy to automate

const KEYS = {
  blue: process.env.KNOXCALL_BLUE_KEY,
  green: process.env.KNOXCALL_GREEN_KEY,
  active: process.env.KNOXCALL_ACTIVE_KEY // "blue" or "green"
};

const currentKey = KEYS[KEYS.active];

​

API Key Rotation Schedule

​

Rotation Strategy 3: Secrets

​

What It Is

Secret: stripe-api-key
- v1: sk_live_old123... (created Jan 1)
- v2: sk_live_new789... (created Mar 15) ← active version

​

When to Rotate

• ✅ Secret exposed or leaked
• ✅ Third-party service rotates their keys (e.g., Stripe rotates automatically)
• ✅ Regular compliance schedule (90 days)
• ✅ Employee with access leaves
• ✅ Moving from test to production

• Zero-downtime rotation (new version immediately active)
• Version history for rollback
• Audit trail of when secrets changed

​

How to Rotate Secrets

​

Step 1: Generate New Secret (Third-Party)

1. Log in to Stripe Dashboard
2. Navigate to Developers → API keys
3. Click Create secret key
4. Name it: “KnoxCall Production Key 2025”
5. Copy the key: sk_live_new789xyz456abc123def789ghi012jkl

​

Step 2: Add New Version in KnoxCall

1. Navigate to Secrets
2. Click the secret (e.g., “stripe-prod-key”)
3. Click Add New Version
4. Paste new secret value:
   Copy

   sk_live_new789xyz456abc123def789ghi012jkl
   
5. Click Save

• New version (v2) becomes active immediately
• All routes using {{secret:stripe-prod-key}} now use v2
• Old version (v1) preserved for rollback

​

Step 3: Test

1. Navigate to Routes → Find routes using this secret
2. Click Test Route
3. Send test request
4. Verify backend receives new secret (check backend logs)

1. Navigate to Secrets → secret detail
2. Click Rollback to v1
3. Investigate issue

​

Step 4: Monitor

✓ Route: stripe-payments - Success (200)
✓ Route: stripe-refunds - Success (200)
✓ Route: stripe-customers - Success (200)

​

Step 5: Revoke Old Secret (Third-Party)

1. Log in to third-party service (Stripe)
2. Revoke old key: sk_live_old123...
3. Confirm

​

Secret Rotation Patterns

​

Pattern 1: Immediate Rotation (Security Incident)

1. Add new version in KnoxCall (0-downtime)
2. Test immediately (< 5 minutes)
3. Revoke old secret in third-party immediately (don’t wait)

​

Pattern 2: Scheduled Rotation (Compliance)

1. Schedule rotation date (e.g., first Monday of quarter)
2. Generate new credentials 1 day before
3. Add new version in KnoxCall
4. Monitor for 48 hours
5. Revoke old credentials

​

Pattern 3: Rolling Window Rotation

Week 1: Rotate Stripe key
Week 2: Rotate SendGrid key
Week 3: Rotate Twilio key
Week 4: Rotate database password

• Spread risk (don’t rotate everything at once)
• Easier to identify issues
• Less overwhelming for team

​

Secret Rotation Checklist

• Identify all routes using the secret
• Generate new credential in third-party service
• Add new version in KnoxCall
• Test all affected routes (Route Tester)
• Monitor logs for 15-30 minutes
• Document rotation (when, why, who)
• Schedule revocation of old secret (24-48 hours)
• Verify old secret revoked in third-party service

​

Rotation Strategy 4: Routes

​

What It Is

• 🔄 Create v2 of API while keeping v1 alive
• 🌍 Duplicate production route for staging
• 🧪 Test configuration changes without affecting live route
• 📦 Clone route to different tenant

​

How to Duplicate Routes

​

Method: Duplicate via UI

1. Navigate to Routes → Click route to duplicate
2. Note all configuration:
   • Target URL
   • Headers
   • Body injection
   • Secrets used
   • Assigned clients
3. Click Create Route
4. Enter new route name (e.g., stripe-payments-v2)
5. Fill in same configuration
6. Save

​

Method: Duplicate via API

​

Route Migration Pattern

Old: stripe-payments (points to api.stripe.com/v1)
New: stripe-payments-v2 (points to api.stripe.com/v2)

• Assign test clients only
• Send test requests
• Verify responses

// Use route based on client
const route = client.useV2 ? "stripe-payments-v2" : "stripe-payments";

fetch(`https://x9y8z7w6.DunderMifflin.knoxcall.com/charges`, {
  headers: {
    "x-knoxcall-route": route
  }
});

• V1 requests declining
• V2 requests increasing

• Disable v1 route
• Monitor for errors
• Delete v1 route after 30 days

​

Rotation Strategy 5: Environments

​

What It Is

• 📋 Clone production config to create new environment
• 🧪 Test environment changes before deploying
• 🌍 Create region-specific environments (US, EU)

​

How to Duplicate Environments

1. Go to Routes → Click route
2. Switch to Environments tab

1. Select environment to copy (e.g., “production”)
2. Click ⋯ (more options)
3. Select Duplicate Environment
4. Enter new environment name: production-eu
5. Click Duplicate

• ✅ Target URL override
• ✅ Header injection overrides
• ✅ Body injection overrides
• ✅ Rate limit overrides
• ✅ Signature settings overrides

• ❌ Assigned clients (you assign separately)

production-eu:
- Target URL: https://api-eu.service.com (changed)
- Headers: (copied from production)
- Secrets: (same as production)

1. Go to Environment Clients tab
2. Select production-eu
3. Assign appropriate clients (e.g., EU servers)

​

Environment Migration Pattern

production → production-new-infra

Old: https://legacy-api.example.com
New: https://new-infra-api.example.com

Client: production-server-01
Environment: production-new-infra

curl -X GET "https://x9y8z7w6.DunderMifflin.knoxcall.com/api/users" \
  -H "x-knoxcall-key: YOUR_KEY" \
  -H "x-knoxcall-route: users" \
  -H "x-knoxcall-environment: production-new-infra"

• Check logs for errors
• Compare response times
• Verify data integrity

Week 1: 1 client (1%)
Week 2: 10 clients (10%)
Week 3: 50 clients (50%)
Week 4: All clients (100%)

1. Update base route configuration to point to new infra
2. Delete production-new-infra environment (no longer needed)

​

Best Practices

​

1. Document Rotation Events

• Audit compliance
• Troubleshooting
• Team awareness

​

2. Test Before Revoking

​

3. Use Grace Periods

• Low risk: 24 hours
• Medium risk: 48 hours
• High risk (leaked): 1 hour minimum

​

4. Automate Where Possible

• Scheduled secret rotation (every 90 days)
• API key rotation (every 90 days)
• Monitoring for rotation events

• Subdomain hash rotation (high impact)
• Route duplication (business logic)

​

5. Use Separate Keys Per Environment

API Keys:
- Production Key A (prod servers)
- Production Key B (prod CI/CD)
- Staging Key (staging servers)
- Development Key (dev laptops)

API Keys:
- One key for everything ❌

​

Rotation Frequency Recommendations

​

Troubleshooting

​

Issue: “Rotation caused downtime”

1. Always deploy new credential first
2. Monitor for 24-48 hours
3. Then revoke old

​

Issue: “Can’t find which routes use a secret”

1. Navigate to Secrets → Click secret
2. View Used By Routes section
3. Lists all routes using this secret

​

Issue: “Rotated secret but old one still being used”

1. Route → Method Configs tab
2. Check each HTTP method
3. Some methods might override with old secret

​

Issue: “Rolled subdomain but clients still using old URL”

// ❌ Don't hardcode
const url = "https://a1b2c3d4.DunderMifflin.knoxcall.com";

// ✅ Use environment variable
const url = process.env.KNOXCALL_BASE_URL;

​

Related Features

• Secret Versioning: Manage multiple versions of secrets
• API Key Management: Create and revoke keys
• Environment Overrides: Per-environment configuration
• Audit Logs: Track all configuration changes

​

Next Steps