​

Creating Your First Secret

​

What is a Secret?

​

Why Use Secrets?

// ❌ Frontend code - API key exposed in browser!
fetch("https://api.stripe.com/charges", {
  headers: {
    "Authorization": "Bearer sk_live_abc123xyz789..."
  }
});

// ✅ Frontend code - No secrets exposed
fetch("https://a1b2c3d4.DunderMifflin.knoxcall.com/api/payments", {
  headers: {
    "x-knoxcall-key": "tk_abc123...",
    "x-knoxcall-route": "stripe-payments"
  }
});

Client Request → KnoxCall → Adds "Authorization: Bearer sk_live_abc..." → Stripe API

​

Secret Types

​

1. String Secrets (Most Common)

• API keys (Stripe, SendGrid, Twilio)
• Passwords (database, services)
• Tokens (auth tokens, webhook secrets)
• Any sensitive string value

​

2. OAuth2 Secrets (Advanced)

• Google OAuth tokens (auto-refreshes when expired)
• Shopify, HubSpot, Microsoft, Slack OAuth
• Stores access token, refresh token, and expiry
• Handles token rotation automatically

​

How Secrets Work

1. You create secret in KnoxCall UI
     ↓
2. Value encrypted with AES-256-GCM
     ↓
3. Stored securely in encrypted vault
     ↓
4. You reference secret in route config: {{secret:stripe_key}}
     ↓
5. Client makes request through KnoxCall
     ↓
6. KnoxCall decrypts secret server-side
     ↓
7. Injects decrypted value into backend request
     ↓
8. Backend receives request with actual API key
     ↓
9. Client never sees the secret value!

​

Create Your First Secret

​

Step 1: Navigate to Secrets

1. Click Resources in the sidebar
2. Select Secrets
3. Click Add Secret

​

Step 2: Choose Secret Type

​

Step 3: Fill in Details

stripe_prod_key

sk_live_abc123xyz789def456ghi789jkl012

Stripe production API key - expires Dec 2025

production, payment, stripe

​

Step 4: Save

​

Use Secret in a Route

​

Step 1: Edit Your Route

1. Navigate to Routes
2. Click your route (e.g., “stripe-payments”)
3. Click Edit

​

Step 2: Inject Secret in Headers

{
  "Authorization": "Bearer {{secret:stripe_prod_key}}"
}

• secret: is required prefix
• name is your secret name (e.g., stripe_prod_key)

{
  "Authorization": "Bearer {{secret:api_key}}"
}

{
  "X-API-Key": "{{secret:sendgrid_key}}"
}

{
  "Authorization": "Basic {{secret:base64_credentials}}"
}

{
  "X-Webhook-Secret": "{{secret:webhook_secret}}",
  "X-App-ID": "{{secret:app_id}}"
}

​

Step 3: Or Inject Secret in Body

{
  "api_key": "{{secret:printnode_key}}",
  "computerId": 123,
  "options": {
    "auth_token": "{{secret:auth_token}}"
  }
}

​

Step 4: Save Route

​

Test Your Secret

​

Make a Request

curl -X POST "https://a1b2c3d4.DunderMifflin.knoxcall.com/api/charge" \
  -H "x-knoxcall-key: tk_abc123..." \
  -H "x-knoxcall-route: stripe-payments" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "usd"}'

​

What Happens

1. KnoxCall receives your request
2. Loads route “stripe-payments”
3. Sees {{secret:stripe_prod_key}} in header template
4. Decrypts secret server-side
5. Replaces template with actual value:
   Copy

   Authorization: Bearer sk_live_abc123xyz789...
   
6. Forwards request to Stripe API with real key
7. Returns response to you

​

View in Logs

1. Navigate to Logs → API Logs
2. Find your request
3. Click to expand details
4. Notice: Request headers show {{secret:stripe_prod_key}} (template)
5. But backend received actual decrypted value

​

Multiple Secrets in One Route

{
  "Authorization": "Bearer {{secret:stripe_key}}",
  "X-Webhook-Secret": "{{secret:webhook_secret}}",
  "X-User-ID": "{{secret:user_id}}"
}

{
  "payment_key": "{{secret:stripe_key}}",
  "notification_key": "{{secret:twilio_key}}",
  "database_url": "{{secret:postgres_url}}"
}

​

Environment-Specific Secrets

​

Create Environment-Specific Secrets

1. Development:
   • Name: stripe_dev_key
   • Value: sk_test_abc123...
2. Staging:
   • Name: stripe_staging_key
   • Value: sk_test_xyz789...
3. Production:
   • Name: stripe_prod_key
   • Value: sk_live_abc123...

​

Configure Route Per Environment

{
  "Authorization": "Bearer {{secret:stripe_prod_key}}"
}

{
  "Authorization": "Bearer {{secret:stripe_dev_key}}"
}

{
  "Authorization": "Bearer {{secret:stripe_staging_key}}"
}

​

Secret Versioning

​

Rotate a Secret

1. Navigate to Secrets
2. Click your secret (e.g., “stripe_prod_key”)
3. Click Add New Version
4. Enter new value:
   Copy

   sk_live_new789xyz123abc456def789
   
5. Save

• New version becomes active immediately
• Old version preserved (for rollback if needed)
• All routes using this secret now use new value
• Zero downtime! No code changes needed

​

View Version History

1. Open secret details
2. Click Version History tab
3. See all versions with timestamps
4. Can rollback to previous version if needed

​

Common Use Cases

​

Payment APIs

{
  "Authorization": "Bearer {{secret:stripe_prod_key}}"
}

{
  "Authorization": "Bearer {{secret:paypal_access_token}}"
}

​

Email/SMS Services

{
  "Authorization": "Bearer {{secret:sendgrid_api_key}}"
}

{
  "X-API-Key": "{{secret:twilio_auth_token}}"
}

​

Webhooks

{
  "X-Webhook-Secret": "{{secret:github_webhook_secret}}"
}

{
  "X-Signature": "{{secret:shopify_hmac_secret}}"
}

​

Database Credentials

{
  "db_url": "{{secret:postgres_connection_string}}"
}

​

Printing Services

{
  "Authorization": "Basic {{secret:printnode_api_key}}"
}

​

Security Best Practices

​

Naming Conventions

stripe_prod_key
sendgrid_dev_api_key
database_password_production
github_webhook_secret_staging

secret1
key
password
temp

• Service (stripe, sendgrid)
• Purpose (api_key, webhook_secret)
• Environment (prod, staging, dev)

​

Secret Rotation

• Critical secrets (payment APIs): Every 90 days
• Less critical: Every 180 days
• Development: Annually

1. Generate new key in third-party service (Stripe, etc.)
2. Create new version in KnoxCall
3. Test in staging first
4. Deploy to production
5. Wait 24-48 hours
6. Revoke old key in third-party service

​

Separation by Environment

• Different secrets for dev/staging/prod
• Never use prod secrets in development
• Test secret rotation in staging first

• Reuse production secrets in development
• Share secrets across unrelated services
• Commit secrets to git (even encrypted)

​

Access Control

• Only give team members access to secrets they need
• Use least privilege principle
• Audit secret access regularly
• Delete unused secrets promptly

​

Monitoring

• Set up alerts for failed secret decryption
• Monitor secret usage in logs
• Track secret rotation dates
• Get notified when secrets expire

​

Troubleshooting

​

Secret Not Found Error

• Typo in secret name
• Secret was deleted
• Wrong syntax (forgot secret: prefix)

1. Check secret exists: Secrets page
2. Verify name spelling matches exactly
3. Check template syntax: {{secret:name}} (not {{name}})

​

Template Not Replaced

• Wrong template syntax
• Secret referenced but not found
• Header injection disabled

1. Check logs - see what was actually sent
2. Verify template syntax is correct
3. Test secret exists and name matches
4. Check inject headers is enabled

​

Wrong Value Injected

• Using wrong environment
• Secret not configured for environment
• Old version being used

1. Check which environment request used
2. Verify secret configured for that environment
3. Check secret version (maybe need to create new version)
4. Look at logs to see which value was injected

​

Next Steps

​

Related Concepts

• Secret Versioning: Track changes and rollback if needed
• Environment Overrides: Different secrets per dev/staging/prod
• Template System: {{secret:name}} syntax for injection
• Encryption: AES-256-GCM with envelope encryption
• OAuth2 Secrets: Automatic token refresh for OAuth flows