Skip to main content

​
Overview

Collection variables are reusable key-value pairs that can be referenced across all routes within a collection. They provide a centralized way to manage configuration values and secret references, ensuring consistency and reducing duplication.

​
Variable Types

​
Value Variables

Standard variables that store plain-text configuration values like API endpoints, timeout settings, or feature flags. Example: 
Key: api_timeout
Value: 30000

​
Secret Variables

Variables that reference encrypted secrets stored in your KnoxCall vault. These are ideal for sensitive data like API keys, passwords, or tokens. Example: 
Key: stripe_api_key
Secret: Stripe Production Key
When a route uses this variable, KnoxCall automatically resolves the secret value from the vault.

​
Creating Variables

1

Navigate to Collection

Open your collection and go to the Variables tab
2

Add Variable

Click the + button in the Variables card header
3

Configure Variable

  • Key: Enter a unique identifier (alphanumeric and underscores only)
  • Type: Choose “Value” for plain text or “Secret” for sensitive data
  • Value/Secret: Enter the value or select an existing secret
  • Description: (Optional) Add notes about the variable’s purpose
4

Save

Click Create to save the variable

​
Using Variables in Routes

Reference collection variables in your routes using the template syntax: 
{{var:variable_name}}

​
Supported Fields

Collection variables can be used in:
  • Target URLs - https://api.example.com/{{var:api_version}}/users
  • Headers - Authorization: Bearer {{var:auth_token}}
  • Query Parameters - ?api_key={{var:api_key}}
  • Request Bodies - JSON values that reference variables

​
Example: Using Variables in a Route

Collection Variables: 
base_domain = api.stripe.com
stripe_secret = [Secret: Stripe Production Key]
api_version = v1
Route Configuration: 
Target URL: https://{{var:base_domain}}/{{var:api_version}}/charges
Headers:
  Authorization: Bearer {{var:stripe_secret}}
  Content-Type: application/json
When a request is proxied, KnoxCall resolves: 
Target URL: https://api.stripe.com/v1/charges
Headers:
  Authorization: Bearer sk_live_xxxxxxxxxxxxx
  Content-Type: application/json

​
Variable Resolution

​
Priority Order

When a variable name appears in multiple places, KnoxCall resolves it in this order:
  1. Environment-specific overrides (coming soon)
  2. Collection variables (current)
  3. Route-level variables (future feature)

​
Environment Context

When using Environment-Specific Secrets, collection variables automatically resolve to the correct environment’s secret value based on the active environment of the route. Example:
  • Variable api_key references secret “API Key”
  • Secret “API Key” has different values for production and staging
  • When route is accessed in production environment → uses production API key
  • When route is accessed in staging environment → uses staging API key

​
Best Practices

Choose clear, self-documenting variable names like stripe_webhook_secret instead of secret1
Always use secret variables (not value variables) for API keys, passwords, tokens, and other sensitive data
Use the Description field to explain what each variable is for and how it should be used
If multiple collections need the same variable, consider if they should be merged into one collection

​
Common Use Cases

​
API Versioning

base_url = https://api.example.com
api_version = v2

Route: {{var:base_url}}/{{var:api_version}}/endpoint

​
Multi-Tenant Configuration

tenant_id = customer_123
tenant_api_key = [Secret: Customer 123 API Key]

Header: X-Tenant-ID: {{var:tenant_id}}
Header: Authorization: Bearer {{var:tenant_api_key}}

​
Feature Flags

enable_new_auth_flow = true
max_retry_attempts = 3

Query: ?use_new_auth={{var:enable_new_auth_flow}}
Query: ?max_retries={{var:max_retry_attempts}}

​
Environment-Specific Endpoints

database_url = [Secret: Production DB Connection String]
cache_ttl = 3600

Config: connection={{var:database_url}}&ttl={{var:cache_ttl}}

​
Managing Variables

​
Editing Variables

  1. Navigate to the Variables tab in your collection
  2. Click on the variable row to open the editor
  3. Modify the value or description
  4. Click Update to save changes

​
Copying Variable References

  1. In the Variables tab, click the ⋯ menu for a variable
  2. Select Copy reference
  3. The variable syntax {{var:key_name}} is copied to your clipboard

​
Deleting Variables

Deleting a variable will break any routes that reference it. Always verify usage before deletion.
  1. Click the ⋯ menu for the variable
  2. Select Delete
  3. Confirm the deletion

​
Troubleshooting

Symptoms: Route shows {{var:key_name}} in logs instead of the actual valueSolutions:
  • Verify the variable key is spelled correctly (case-sensitive)
  • Check that the variable exists in the collection
  • Ensure the route is assigned to the correct collection
Symptoms: Secret variable resolves to empty stringSolutions:
  • Verify the secret exists and has a value
  • Check that the secret is not deleted
  • For environment-specific secrets, ensure the secret has a value for the active environment
Symptoms: Can’t create variable with certain charactersSolutions:
  • Variable keys must be alphanumeric plus underscores only
  • Use api_key instead of api-key or api.key
  • Keys cannot start with a number

​
Next Steps

Environment-Specific Secrets

Learn how to use different secret values per environment

Collection Environment Defaults

Configure default settings per environment at the collection level