Collection Variables

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

Navigate to Collection

Open your collection and go to the Variables tab

Add Variable

Click the + button in the Variables card header

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

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:

Environment-specific overrides (coming soon)
Collection variables (current)
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

Use Descriptive Keys

Choose clear, self-documenting variable names like stripe_webhook_secret instead of secret1

Leverage Secret Variables for Credentials

Always use secret variables (not value variables) for API keys, passwords, tokens, and other sensitive data

Document Your Variables

Use the Description field to explain what each variable is for and how it should be used

Avoid Duplication

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

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

Copying Variable References

In the Variables tab, click the ⋯ menu for a variable
Select Copy reference
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.

Click the ⋯ menu for the variable
Select Delete
Confirm the deletion

Troubleshooting

Variable Not Resolving

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

Secret Variable Shows as Empty

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

Variable Key Validation Error

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

Managing Collections

Dynamic DB Credentials overview

​Collection Variables

​Overview

​Variable Types

​Value Variables

​Secret Variables

​Creating Variables

​Using Variables in Routes

​Supported Fields

​Example: Using Variables in a Route

​Variable Resolution

​Priority Order

​Environment Context

​Best Practices

​Common Use Cases

​API Versioning

​Multi-Tenant Configuration

​Feature Flags

​Environment-Specific Endpoints

​Managing Variables

​Editing Variables

​Copying Variable References

​Deleting Variables

​Troubleshooting

​Next Steps

Environment-Specific Secrets

Collection Environment Defaults

Collection Variables

Overview

Variable Types

Value Variables

Secret Variables

Creating Variables

Using Variables in Routes

Supported Fields

Example: Using Variables in a Route

Variable Resolution

Priority Order

Environment Context

Best Practices

Common Use Cases

API Versioning

Multi-Tenant Configuration

Feature Flags

Environment-Specific Endpoints

Managing Variables

Editing Variables

Copying Variable References

Deleting Variables

Troubleshooting

Next Steps