Using Secrets in Routes

Learn how to inject encrypted secrets into your route requests using KnoxCall’s template system.

Template Syntax

Secrets are injected using template syntax in your route configuration.

Basic Format

{{secret:SECRET_NAME}}

Components:

{{ - Opening delimiter
secret: - Type identifier (required)
SECRET_NAME - Your secret’s name
}} - Closing delimiter

Example

If you have a secret named stripe_prod_key:

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

At runtime, KnoxCall replaces this with:

{
  "Authorization": "Bearer sk_live_EXAMPLE_abc123xyz789..."
}

Injecting Secrets in Headers

The most common use case - adding secrets to HTTP headers.

Step 1: Edit Route

Go to Routes
Click on your route
Scroll to Inject Headers section

Step 2: Add Header with Secret

Click Add Header or edit the JSON directly:

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

Step 3: Save

Click Save Changes ✅ All requests through this route now have the secret injected!

Common Header Patterns

Bearer Token

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

Used by: Stripe, GitHub, most REST APIs

API Key Header

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

Used by: SendGrid, Mailgun, custom APIs

Basic Authentication

{
  "Authorization": "Basic {{secret:basic_auth_credentials}}"
}

Note: Secret value should be base64-encoded username:password

Custom Headers

{
  "X-Custom-Token": "{{secret:custom_token}}",
  "X-Webhook-Secret": "{{secret:webhook_secret}}",
  "X-Client-ID": "{{secret:client_id}}"
}

Injecting Secrets in the Request Body

KnoxCall can substitute placeholders inside the request body your client sends — not just headers. This lets your application reference secrets by name (or by ID) without ever holding the actual values. KnoxCall resolves the placeholders server-side, swaps them for the real decrypted values, and forwards the rewritten body upstream.

How it works

Your client sends a POST/PUT/PATCH with placeholder tokens in the body
KnoxCall reads the body, scans for {{secret:name}} / {{secret_id:uuid}} / {{var:key}}
KnoxCall checks that each secret named is one the route’s own template already sends (see below), then resolves it against your tenant’s secrets for the route’s active environment
KnoxCall rewrites Content-Length and forwards the substituted body to the upstream API
Your application never needs to possess the raw credential

Which secrets your client may name

A placeholder your client sends resolves only for a secret the route already sends: one that the route’s own header or body template references, for the method you are calling. The same rule applies to placeholders your client puts in request headers. If your client names any other secret in your account, KnoxCall refuses the request with 403 and X-Knox-Error: client_placeholder_not_bound. The secret it names is never decrypted, and nothing reaches the upstream API. The error message is the same whether or not the named secret exists. If KnoxCall cannot complete that check, for example during a brief database outage, it refuses the request with 503 and X-Knox-Error: client_placeholder_binding_unavailable rather than forwarding it. Nothing reaches the upstream API, and the request is safe to retry. This stops a credential that can call one route from pulling a different route’s secret into a request it controls.

Same secret, either form. If the route’s template sends {{secret_id:550e8400-e29b-41d4-a716-446655440000}}, your client may send that placeholder or the same secret by name, {{secret:stripe_prod_key}}.
This method’s template. If the route has a different configuration per HTTP method, only the configuration for the method you are calling counts. A secret that only the DELETE configuration sends cannot be named in a POST.
Not the mTLS certificate. A route’s client certificate is presented during the TLS handshake and never sent in a request, so a client cannot name it.
Accounts created before this rule was deployed are report-only until they are switched over: the placeholder still resolves, and each use is recorded in your audit log as route.client_placeholder_not_bound. Accounts created since are refused as described above.

The examples below assume the route’s own header template already sends the secret they name.

Placeholder forms accepted in the body

Form	Lookup	Example	Recommended
`{{secret_id:UUID}}`	By secret UUID — stable, rename-safe	`{{secret_id:550e8400-e29b-41d4-a716-446655440000}}`	✅ Preferred
`{{secret:NAME}}`	By secret name — legacy, human-friendly	`{{secret:stripe_prod_key}}`	⚠️ Works, but breaks on rename
`{{var:QUERY_PARAM}}`	Value of an incoming query string parameter	`{{var:user_id}}`	—

Prefer the UUID form ({{secret_id:...}}) wherever possible. A secret’s UUID is permanent and never changes, so your code and templates keep working even if someone renames the secret in the dashboard. The name-based form ({{secret:...}}) is supported for backwards compatibility and readability, but any rename will silently break every reference to it and the next request will hard-fail with “Missing secret”.Also note: {{secret:UUID}} is not a shortcut for ID-based lookup — it would try to find a secret literally named that UUID string and fail. For ID lookups always use the secret_id: prefix.

You can find a secret’s UUID on its detail page in the KnoxCall dashboard, or in the response of the create_secret API / onboarding-agent tool call.

Example — JSON body

Your client code sends this to KnoxCall (UUID form recommended; YOUR_ACCESS_TOKEN is a kc_… OAuth access token — see Authentication):

POST https://YOUR-SUBDOMAIN.knoxcall.com/v1/charges
Content-Type: application/json
x-knoxcall-route: ROUTE_SLUG
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "api_key": "{{secret_id:550e8400-e29b-41d4-a716-446655440000}}",
  "amount": 1000,
  "currency": "usd"
}

What the upstream API actually receives:

POST /v1/charges HTTP/1.1
Host: api.stripe.com

{
  "api_key": "sk_live_EXAMPLE_abc123xyz789...",
  "amount": 1000,
  "currency": "usd"
}

Example — form-urlencoded

POST https://YOUR-SUBDOMAIN.knoxcall.com/send
Content-Type: application/x-www-form-urlencoded

api_key={{secret_id:550e8400-e29b-41d4-a716-446655440000}}&to=%2B15551234567&body=hello

Example — plain text / XML

POST https://YOUR-SUBDOMAIN.knoxcall.com/soap
Content-Type: application/xml

<?xml version="1.0"?>
<Envelope>
  <Auth>{{secret_id:550e8400-e29b-41d4-a716-446655440000}}</Auth>
  <Action>GetInvoice</Action>
</Envelope>

Supported Content-Types

KnoxCall only rewrites bodies for text-shaped Content-Types, so binary uploads stay byte-identical:

Content-Type	Body injection
`application/json`	✅
`application/xml`, `text/xml`, `application/*+xml`	✅
`application/*+json` (e.g. `application/vnd.api+json`)	✅
`application/x-www-form-urlencoded`	✅
`application/javascript`, `application/ecmascript`	✅
`text/*` (plain, html, csv, etc.)	✅
`multipart/form-data`	❌ passed through unchanged
`application/octet-stream`, `image/`, `audio/`, `video/*`, `application/pdf`	❌ passed through unchanged

Safety rules

Tenant isolation — clients can only reference secrets belonging to their own tenant. A UUID guessed from another tenant will hard-fail.
Route binding — clients can only reference a secret the route itself already sends. Any other secret is refused with 403 client_placeholder_not_bound before it is decrypted; accounts created before this rule was deployed are report-only until switched over (see Which secrets your client may name).
Environment-aware — KnoxCall resolves secrets against the route’s active environment. If the secret has no value for that environment, the request fails with a clear error (no silent fallback).
Size limit — bodies larger than 1 MiB pass through without substitution to protect the proxy (configurable via BODY_INJECTION_MAX_BYTES).
UTF-8 required — the body must be valid UTF-8 with no NUL bytes; anything else is treated as binary and passed through untouched.
Hard-fail on missing secrets — referencing a secret that doesn’t exist (or has no value in the active environment) returns an error instead of sending an empty string upstream.
Logs are scrubbed — audit logs store the body with placeholders intact, never the resolved secret values.

Do I still need headers?

Yes: configure the route’s template first. A placeholder your client sends, in the body or in a header, resolves only for a secret that the route’s own inject_headers_json or inject_body_json template already references for the method you are calling. Any other secret is refused with 403 client_placeholder_not_bound, so a client placeholder is not a way to pick a secret per call. Use the route’s header template for stable auth (e.g. Authorization: Bearer). Use a body placeholder where the upstream API expects that same credential inside the payload.

Common Body Patterns

All examples use the recommended UUID form — substitute your actual secret IDs.

Simple API key in body (UUID, rename-safe)

{ "api_key": "{{secret_id:550e8400-e29b-41d4-a716-446655440000}}" }

Nested objects

{
  "credentials": {
    "username": "admin",
    "password": "{{secret_id:7a4c1f22-9e8b-4d60-9b32-12e1f4b9c8a1}}"
  }
}

Legacy name form (works, but breaks if the secret is renamed)

{ "api_key": "{{secret:service_api_key}}" }

Multiple secrets in one request

{
  "payment_key": "{{secret_id:550e8400-e29b-41d4-a716-446655440000}}",
  "email_key":   "{{secret_id:6b1f2f33-c1a4-4f75-a0b7-8d91e2a6f3c2}}",
  "sms_key":     "{{secret_id:a9c82e44-ff3a-4210-9c63-1b8f5cf9e7d1}}"
}

Mixing a secret with a query-string variable

POST /notify?user_id=42
Content-Type: application/json

{
  "user":  "{{var:user_id}}",
  "token": "{{secret_id:550e8400-e29b-41d4-a716-446655440000}}"
}

Multiple Secrets in One Route

You can use multiple different secrets in the same route configuration.

Example: Multi-Service Integration

Route: notification-service Headers:

{
  "X-Email-Key": "{{secret:sendgrid_api_key}}",
  "X-SMS-Key": "{{secret:twilio_auth_token}}"
}

Body:

{
  "email_config": {
    "api_key": "{{secret:sendgrid_api_key}}"
  },
  "sms_config": {
    "auth_token": "{{secret:twilio_auth_token}}",
    "account_sid": "{{secret:twilio_account_sid}}"
  },
  "push_config": {
    "server_key": "{{secret:fcm_server_key}}"
  }
}

Result: All 4 secrets injected in one request!

Environment-Specific Secrets

Use different secrets per environment (dev, staging, production).

Setup

Create environment-specific secrets:

Production:

Name: stripe_prod_key
Value: sk_live_abc123...

Staging:

Name: stripe_staging_key
Value: sk_test_xyz789...

Development:

Name: stripe_dev_key
Value: sk_test_dev123...

Configure Route Per Environment

Base environment (production):

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

Override for staging:

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

Override for development:

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

How to Set Up

Go to route → Environment tab
Select “staging”

Edit Inject Headers:

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

Save
Repeat for “development”

Result:

Production uses: stripe_prod_key
Staging uses: stripe_staging_key
Development uses: stripe_dev_key

All with the same route!

Method-Specific Secrets

Different secrets for different HTTP methods on the same route.

Example Scenario

Route handles both GET (read) and POST (write) to same API:

GET needs read-only key
POST needs full-access key

Setup

GET method config:

{
  "method": "GET",
  "inject_headers_json": {
    "Authorization": "Bearer {{secret:api_read_only_key}}"
  }
}

POST method config:

{
  "method": "POST",
  "inject_headers_json": {
    "Authorization": "Bearer {{secret:api_full_access_key}}"
  }
}

Result:

GET requests use read-only key
POST requests use full-access key

Secret Resolution Order

When multiple environments and methods are involved, KnoxCall resolves secrets in this order:

Method-specific environment override
Environment override (if method not specified)
Base route configuration

Example

Request: POST to route in "staging" environment

Lookup order:
1. Check: staging → POST method config → secrets
2. If not found: staging → default config → secrets
3. If not found: base (production) → POST method config → secrets
4. If not found: base (production) → default config → secrets

Template Syntax Rules

✅ Correct Syntax

{
  "Authorization": "Bearer {{secret:stripe_key}}"
}

Rules:

Double curly braces: {{ and }}
Prefix: secret:
No spaces inside braces
Lowercase with underscores for secret names

❌ Common Mistakes

// ❌ Single braces
{
  "Authorization": "Bearer {secret:stripe_key}"
}

// ❌ No prefix
{
  "Authorization": "Bearer {{stripe_key}}"
}

// ❌ Wrong prefix
{
  "Authorization": "Bearer {{env:stripe_key}}"
}

// ❌ Spaces inside
{
  "Authorization": "Bearer {{ secret:stripe_key }}"
}

// ❌ Hyphens in name
{
  "Authorization": "Bearer {{secret:stripe-key}}"
}

Real-World Examples

Example 1: Stripe Payments

Secret:

Name: stripe_prod_key
Value: sk_live_EXAMPLE_abc123xyz789...

Route config:

{
  "inject_headers_json": {
    "Authorization": "Bearer {{secret:stripe_prod_key}}",
    "Content-Type": "application/json"
  }
}

Actual request sent to Stripe:

POST /v1/charges HTTP/1.1
Host: api.stripe.com
Authorization: Bearer sk_live_EXAMPLE_abc123xyz789...
Content-Type: application/json

{"amount": 1000, "currency": "usd"}

Example 2: SendGrid Email

Secret:

Name: sendgrid_api_key
Value: SG.abc123xyz789...

Route config:

{
  "inject_headers_json": {
    "Authorization": "Bearer {{secret:sendgrid_api_key}}",
    "Content-Type": "application/json"
  },
  "inject_body_json": {
    "personalizations": [{
      "to": [{"email": "user@example.com"}]
    }],
    "from": {"email": "noreply@acme.com"},
    "subject": "Welcome!",
    "content": [{
      "type": "text/html",
      "value": "<p>Welcome!</p>"
    }]
  }
}

Example 3: Database Access

Secret:

Name: postgres_connection_url
Value: postgres://user:pass@host:5432/db

Route config:

{
  "inject_body_json": {
    "connection_string": "{{secret:postgres_connection_url}}",
    "query": "SELECT * FROM users WHERE id = $1",
    "params": [123]
  }
}

Example 4: PrintNode Printing

Secret:

Name: printnode_api_key
Value: abc123xyz789...

Route config:

{
  "inject_headers_json": {
    "Authorization": "Basic {{secret:printnode_api_key}}"
  },
  "inject_body_json": {
    "printerId": 123,
    "title": "Receipt",
    "contentType": "pdf_uri",
    "content": "https://example.com/receipt.pdf",
    "source": "KnoxCall POS"
  }
}

Example 5: Multi-Service Orchestration

Secrets:

stripe_key
sendgrid_key
twilio_key

Route config:

{
  "inject_headers_json": {
    "X-Service": "orchestrator"
  },
  "inject_body_json": {
    "actions": [
      {
        "service": "payment",
        "api_key": "{{secret:stripe_key}}",
        "action": "charge"
      },
      {
        "service": "email",
        "api_key": "{{secret:sendgrid_key}}",
        "action": "send_receipt"
      },
      {
        "service": "sms",
        "api_key": "{{secret:twilio_key}}",
        "action": "send_notification"
      }
    ]
  }
}

Combining Secrets with Other Templates

You can combine secrets with the other supported template forms in a single body or header set:

{
  "Authorization": "Bearer {{secret_id:550e8400-e29b-41d4-a716-446655440000}}",
  "X-Legacy-Key": "{{secret:api_key}}",
  "X-User-ID": "{{var:user_id}}"
}

Supported placeholder forms:

{{secret_id:UUID}} - Inject a secret by its UUID (preferred — rename-safe)
{{secret:name}} - Inject a secret by its name (legacy — breaks on rename)
{{var:QUERY_PARAM}} - Substitute the value of an incoming query-string parameter

These are the only placeholder forms the template engine resolves. Tokens such as {{header:name}}, {{env:name}}, or {{uuid}} are not supported and are passed through to the upstream unchanged.

Security Considerations

What Gets Logged

In KnoxCall logs:

Template syntax shown: {{secret:stripe_key}}
Actual value: Never logged

Example log entry:

{
  "request_headers": {
    "Authorization": "Bearer {{secret:stripe_key}}"
  }
}

Plaintext value is not exposed in logs for security.

Secret Transmission

Flow:

1. Client makes request to KnoxCall
   ↓
2. KnoxCall receives request
   ↓
3. Loads route configuration
   ↓
4. Sees {{secret:stripe_key}} template
   ↓
5. Decrypts secret SERVER-SIDE
   ↓
6. Replaces template with plaintext
   ↓
7. Forwards request to backend
   ↓
8. Backend receives real API key
   ↓
9. Client NEVER sees the plaintext!

Best Practices

✅ Do:

Use secrets for all sensitive values
Separate secrets per environment
Rotate secrets regularly
Use descriptive secret names
Document what each secret is for

❌ Don’t:

Hardcode API keys in route configs
Use production secrets in development
Share secrets via email or chat
Commit secrets to git
Use generic names like “key” or “secret”

Troubleshooting

Secret Not Replacing

Symptom: Backend receives {{secret:stripe_key}} literally. Causes:

Syntax error in template
Secret doesn’t exist
Secret name typo

Debug steps:

Check template syntax: {{secret:name}}
Verify secret exists: Resources → Secrets
Check spelling matches exactly (case-sensitive)
Look at logs for error messages

Wrong Value Injected

Symptom: Wrong API key being used. Causes:

Using wrong environment
Wrong secret name
Secret not configured for environment

Fix:

Check which environment request is using
Verify environment override has correct secret
Check secret name spelling

Secret Not Found Error

Error: Secret 'api_key' not found Solution:

Go to Resources → Secrets
Check secret exists
Verify name matches template exactly
Check no typos: api_key vs api_key_

Value Not Decrypting

Symptom: Encrypted value sent instead of plaintext. Cause: KnoxCall internal error (very rare). Solution:

Check KnoxCall status
Try creating new secret version
Contact support if persists

Testing Secret Injection

Test Endpoint

Use a test endpoint to verify secret injection:

Create test route:
- Target: https://httpbin.org/anything
- Method: POST

Add secret in header:

{
  "X-Test-Secret": "{{secret:test_api_key}}"
}

Make request:

# $TOKEN is a kc_… OAuth access token — see /api-reference/authentication
curl -X POST https://YOUR-SUBDOMAIN.knoxcall.com/anything \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-knoxcall-route: test-route"

Check response:

{
  "headers": {
    "X-Test-Secret": "your-actual-secret-value-here"
  }
}

✅ If you see actual value, injection works!

Quick Reference

Use Case	Template Syntax	Example
Header	`{{secret:name}}`	`"Authorization": "Bearer {{secret:api_key}}"`
Body	`{{secret:name}}`	`"api_key": "{{secret:api_key}}"`
Multiple	Multiple templates	`{{secret:key1}}` and `{{secret:key2}}`
Environment	Different secret per env	Production: `{{secret:prod_key}}`

Next Steps

Creating Secrets

How to create and manage secrets

Secrets Overview

Complete secrets guide

Environment Basics

Environment-specific secrets

OAuth2 Flow

Auto-refreshing OAuth2 tokens

Pro Tip: Always test secret injection with a test endpoint (like httpbin.org) before using in production. This lets you verify the actual decrypted value is correct.

​Using Secrets in Routes

​Template Syntax

​Basic Format

​Example

​Injecting Secrets in Headers

​Step 1: Edit Route

​Step 2: Add Header with Secret

​Step 3: Save

​Common Header Patterns

​Bearer Token

​API Key Header

​Basic Authentication

​Custom Headers

​Injecting Secrets in the Request Body

​How it works

​Which secrets your client may name

​Placeholder forms accepted in the body

​Example — JSON body

​Example — form-urlencoded

​Example — plain text / XML

​Supported Content-Types

​Safety rules

​Do I still need headers?

​Common Body Patterns

​Simple API key in body (UUID, rename-safe)

​Nested objects

​Legacy name form (works, but breaks if the secret is renamed)

​Multiple secrets in one request

​Mixing a secret with a query-string variable

​Multiple Secrets in One Route

​Example: Multi-Service Integration

​Environment-Specific Secrets

​Setup

​Configure Route Per Environment

​How to Set Up

​Method-Specific Secrets

​Example Scenario

​Setup

​Secret Resolution Order

​Example

​Template Syntax Rules

​✅ Correct Syntax

​❌ Common Mistakes

​Real-World Examples

​Example 1: Stripe Payments

​Example 2: SendGrid Email

​Example 3: Database Access

​Example 4: PrintNode Printing

​Example 5: Multi-Service Orchestration

​Combining Secrets with Other Templates

​Security Considerations

​What Gets Logged

​Secret Transmission

​Best Practices

​Troubleshooting

​Secret Not Replacing

​Wrong Value Injected

​Secret Not Found Error

​Value Not Decrypting

​Testing Secret Injection

​Test Endpoint

​Quick Reference

​Next Steps

Creating Secrets

Secrets Overview

Environment Basics

OAuth2 Flow

Using Secrets in Routes

Template Syntax

Basic Format

Example

Injecting Secrets in Headers

Step 1: Edit Route

Step 2: Add Header with Secret

Step 3: Save

Common Header Patterns

Bearer Token

API Key Header

Basic Authentication

Custom Headers

Injecting Secrets in the Request Body

How it works

Which secrets your client may name

Placeholder forms accepted in the body

Example — JSON body

Example — form-urlencoded

Example — plain text / XML

Supported Content-Types

Safety rules

Do I still need headers?

Common Body Patterns

Simple API key in body (UUID, rename-safe)

Nested objects

Legacy name form (works, but breaks if the secret is renamed)

Multiple secrets in one request

Mixing a secret with a query-string variable

Multiple Secrets in One Route

Example: Multi-Service Integration

Environment-Specific Secrets

Setup

Configure Route Per Environment

How to Set Up

Method-Specific Secrets

Example Scenario

Setup

Secret Resolution Order

Example

Template Syntax Rules

✅ Correct Syntax

❌ Common Mistakes

Real-World Examples

Example 1: Stripe Payments

Example 2: SendGrid Email

Example 3: Database Access

Example 4: PrintNode Printing

Example 5: Multi-Service Orchestration

Combining Secrets with Other Templates

Security Considerations

What Gets Logged

Secret Transmission

Best Practices

Troubleshooting

Secret Not Replacing

Wrong Value Injected

Secret Not Found Error

Value Not Decrypting

Testing Secret Injection

Test Endpoint

Quick Reference

Next Steps