> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Collection Variables

> Use variables to share configuration values and secrets across routes in a collection

# 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:**

```text theme={"dark"}
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:**

```text theme={"dark"}
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

<Steps>
  <Step title="Navigate to Collection">
    Open your collection and go to the **Variables** tab
  </Step>

  <Step title="Add Variable">
    Click the **+** button in the Variables card header
  </Step>

  <Step title="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
  </Step>

  <Step title="Save">
    Click **Create** to save the variable
  </Step>
</Steps>

## Using Variables in Routes

Reference collection variables in your routes using the template syntax:

```text theme={"dark"}
{{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:**

```text theme={"dark"}
base_domain = api.stripe.com
stripe_secret = [Secret: Stripe Production Key]
api_version = v1
```

**Route Configuration:**

```text theme={"dark"}
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:

```text theme={"dark"}
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](/essentials/secrets/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

<AccordionGroup>
  <Accordion title="Use Descriptive Keys" icon="text">
    Choose clear, self-documenting variable names like `stripe_webhook_secret` instead of `secret1`
  </Accordion>

  <Accordion title="Leverage Secret Variables for Credentials" icon="key">
    Always use secret variables (not value variables) for API keys, passwords, tokens, and other sensitive data
  </Accordion>

  <Accordion title="Document Your Variables" icon="file-text">
    Use the Description field to explain what each variable is for and how it should be used
  </Accordion>

  <Accordion title="Group Related Variables" icon="folder">
    Organize variables by prefix: `stripe_api_key`, `stripe_webhook_secret`, `stripe_account_id`
  </Accordion>

  <Accordion title="Avoid Duplication" icon="copy">
    If multiple collections need the same variable, consider if they should be merged into one collection
  </Accordion>
</AccordionGroup>

## Common Use Cases

### API Versioning

```text theme={"dark"}
base_url = https://api.example.com
api_version = v2

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

### Multi-Tenant Configuration

```text theme={"dark"}
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

```text theme={"dark"}
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

```text theme={"dark"}
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

<Warning>
  Deleting a variable will break any routes that reference it. Always verify usage before deletion.
</Warning>

1. Click the **⋯** menu for the variable
2. Select **Delete**
3. Confirm the deletion

## Troubleshooting

<AccordionGroup>
  <Accordion title="Variable Not Resolving" icon="circle-exclamation">
    **Symptoms:** Route shows `{{var:key_name}}` in logs instead of the actual value

    **Solutions:**

    * 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
  </Accordion>

  <Accordion title="Secret Variable Shows as Empty" icon="key">
    **Symptoms:** Secret variable resolves to empty string

    **Solutions:**

    * 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
  </Accordion>

  <Accordion title="Variable Key Validation Error" icon="triangle-exclamation">
    **Symptoms:** Can't create variable with certain characters

    **Solutions:**

    * Variable keys must be alphanumeric plus underscores only
    * Use `api_key` instead of `api-key` or `api.key`
    * Keys cannot start with a number
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Environment-Specific Secrets" icon="layer-group" href="/essentials/secrets/environment-specific-secrets">
    Learn how to use different secret values per environment
  </Card>

  <Card title="Collection Environment Defaults" icon="settings" href="/essentials/environments/collection-environment-defaults">
    Configure default settings per environment at the collection level
  </Card>
</CardGroup>