Collection Environment Defaults

When all the routes in a collection share the same shape — the same environments, the same target host pattern, the same set of clients — it’s tedious (and error-prone) to configure each route individually. Collection environment defaults let you declare what a collection expects once, and every route in the collection automatically picks it up.

What You Can Define

For each collection, you configure:

Setting	Scope	Description
Expected environments	Collection	The list of environments routes in this collection should have (e.g. `production`, `development`)
Base URL	Per environment	The default target host used when prefilling new routes
Default clients	Per environment	Clients automatically attached to routes in that environment
Header injections	Per environment	(Reserved for future use)
Body injections	Per environment	(Reserved for future use)

Expected environments is a list, not a single value. A Shopify collection might expect both production and development, so every route in it is guaranteed to have both configured.

Why Use Collection Defaults?

Without Defaults

Every time you add a route to a collection, you have to remember to:

Create a production environment config
Create a development environment config
Paste the same base URL everywhere
Attach the same four or five clients on both environments
Hope nobody forgets a step three weeks from now

With Defaults

Declare once — “This collection has production and development, base URLs are X and Y, and these clients are always attached.”
Auto-provision on join — When a route joins the collection, missing environments are created silently from the defaults.
Prefill on create — The route creation form fills in the base URL from the collection.
Drift detection — Routes that drift from the defaults are flagged on both the collection page (sync stats) and the route page (clients compare row).
One-click reset — Bring a route back to the canonical client list with a single click.

Setting Up Defaults

1. Open the Collection’s Environments Tab

Navigate to Collections → your collection → Environments tab.

2. Declare Expected Environments

At the top of the tab, click any environment chip to add or remove it from the expected list.

Expected environments:  [✓ production]  [✓ development]  [ staging ]

Removing an environment from the expected list only stops auto-provisioning going forward. Existing route environment configs are preserved, not deleted. If any routes already use that environment, you’ll be warned before the change is applied.

3. Configure Each Environment

Pick an environment from the dropdown and fill in:

Base URL — e.g. https://api.shopify.com for production, https://sandbox.shopify.com for development
Default clients — Add the clients that should automatically be attached to every route in this collection+environment

4. Save

Unsaved changes are shown in a sticky save bar at the bottom of the tab. Click Save to persist.

Saving only updates the collection’s defaults — it does not automatically apply them to existing routes. Use Apply to routes to push changes out.

Auto-Provision on Join

When a route joins a collection (either at creation time or by changing its collection later), KnoxCall silently creates any missing environment configs from the collection defaults.

Route joins "Shopify APIs" collection
   └─ Collection expects: [production, development]
   └─ Route currently has: [production]

   Result: development is auto-created with:
     • Base URL from collection
     • Default clients from collection
     • inject_headers / inject_body from collection (when configured)

This happens silently — no modal, no confirmation. Routes always have every environment the collection expects.

Auto-provisioning respects tenant boundaries: environments that don’t exist for your tenant are skipped.

Base URL Prefill on Route Creation

When creating a new route, selecting a collection triggers a preview panel showing the environments that will be provisioned. At the same time, the target URL input is prefilled with the first expected environment’s base URL. A small hint appears below the input:

Prefilled from collection (production) — click to edit

As soon as you start typing, the prefill is locked out — KnoxCall will never overwrite a value you’ve explicitly edited.

Keeping Routes in Sync

Defaults change over time. When they do, KnoxCall helps you bring existing routes back in line.

The Sync Stats Row

On the collection’s Environments tab, below the default-clients editor, a sync row shows:

12 routes • 8 synced • 3 out of sync • 1 missing env         [ Apply to routes ]

Synced — The route’s client list matches the defaults exactly.
Out of sync — The route is missing some defaults, has extra clients, or both.
Missing env — The route has no config for this environment yet.

Clicking Apply to routes opens a modal that shows every route in the collection with its individual diff:

+ ClientName (will be added) — Missing defaults that will be attached.
− ClientName (will be removed) — Extras that will be detached (replace mode only).
(keeping: ClientName) — Extras that will be preserved (merge mode).

You choose the apply mode:

Merge (recommended)

Add missing defaults, preserve any extra clients already on the route.Safe for routes that legitimately have extra clients.

Replace all

Hard sync: add defaults, remove anything not in the defaults.Use when the defaults must be authoritative.

Routes that are out-of-sync or missing-env are preselected by default, so one click catches you up on everything.

The Route-Level Compare Row

Open any route in a collection that has defaults. On the Clients tab, the client compare widget adds a {collection} default row (for example, Shopify APIs default) showing the canonical client list for the current environment. When the route’s clients differ from — or are missing — those defaults, the row exposes a single Apply action.

Out of Sync

The compare row shows the collection’s desired client list alongside the route’s current one. The Apply action is titled:

Reset production to Shopify APIs defaults

Triggering it performs a hard replace — extra clients are removed, defaults are added exactly. This is the intentional, explicit way to snap a single route back to canonical.

Missing Env

When the route has no config for an environment the collection expects, the compare row’s Apply action is titled instead:

Provision development from Shopify APIs defaults

Triggering it creates the environment config for this route using the collection’s base URL and default clients.

The compare row is part of the clients comparison widget — there’s no separate banner to dismiss. It simply reflects the current diff and disappears once the route is in sync.

Merge vs Replace: When to Use Each

Situation	Use	Why
Routine sync after adding a default client	Merge (bulk)	Safe — won’t clobber route-specific extras
Onboarding a fleet of existing routes into a collection	Merge (bulk)	Adds missing defaults without surprises
A single route has drifted and you want it back to canonical	Reset (compare row)	Explicit per-route hard sync
The collection is the single source of truth and extras are forbidden	Replace (bulk)	Enforces exact defaults on every route

Real-World Example

Scenario: An e-commerce team has a “Shopify APIs” collection with 8 routes. They always run routes in both production and development, and every route needs the monitoring-probe, office-vpn, and ci-runner clients.

Step 1: Configure the collection once

Collection: Shopify APIs
Expected environments: [production, development]

Production:
  Base URL:        https://api.shopify.com
  Default clients: monitoring-probe, office-vpn, ci-runner

Development:
  Base URL:        https://sandbox.shopify.com
  Default clients: monitoring-probe, office-vpn, ci-runner, dev-laptop

Step 2: Add a new route

The developer creates shopify-orders and picks the Shopify APIs collection. KnoxCall:

Shows a preview: “will pre-configure 2 environments”
Prefills the target URL with https://api.shopify.com
On save, auto-provisions the development environment with its base URL and 4 default clients

No manual client-attachment, no copy-paste of URLs.

Step 3: Add a new default client

Three months later, the team adds newrelic-probe to the collection defaults and clicks Apply to routes with Merge mode. All 8 routes receive newrelic-probe on both environments — without disturbing any route-specific extras.

Step 4: A stray route

A single route shopify-legacy-sync was modified by hand and has legacy-jenkins attached. Opening its clients tab shows the compare row out of sync with the Shopify APIs default — newrelic-probe will be added. The developer triggers the Reset production to Shopify APIs defaults action. legacy-jenkins is removed, newrelic-probe is added, and the route matches canonical.

How It Differs from Collection Variables & Inheritance

KnoxCall collections have two related — but separate — systems:

Feature	What It Does
Collection variables	Resolves `{{var:name}}` template placeholders in route configs at proxy time
`inherit_collection_config` / `inherit_collection_auth`	At proxy time, pulls the collection’s base URL or auth config if the route doesn’t set its own
Collection environment defaults (this page)	Stamps values onto the route itself when it joins the collection or when you click Apply — the route then owns the values

In other words:

Inheritance is a proxy-time lookup — change the collection, every route changes instantly.
Defaults are a create-time / apply-time stamp — routes own their values, but can be brought back in sync on demand.

Use inheritance for values that should be always the collection’s; use defaults for values that are typically the collection’s but routes may legitimately override.

Audit Trail

Every defaults operation is logged to Audit Logs:

Action	When
`collection_defaults.apply`	Bulk apply with merge or replace
`route_environment.reset_to_collection_defaults`	Per-route reset via the compare row Apply action
`route_environment.provisioned_from_collection`	Per-route provision via the compare row Apply action
`route_environment.auto_provisioned`	Automatic provision when a route joined a collection

Each entry records the collection, environment, route(s) affected, and the mode used.

Best Practices

✅ Do

Declare expected environments early. Set them before adding routes so auto-provisioning catches everything.
Prefer Merge over Replace for bulk apply. Merge is the safe default; Replace should be a deliberate choice.
Use Reset (per-route compare row) for drift fixes. It’s unambiguous and audit-logged per route.
Review the Apply modal’s diff before confirming. The preselection helps, but eyeballing it catches surprises.

❌ Don’t

Don’t use Replace to “clean up” routes you don’t fully understand. Extras may be there for a reason.
Don’t remove an expected environment to hide drift. The warning flow lets you remove it, but the underlying route configs stay — the drift just becomes invisible.
Don’t rely on defaults for proxy-time behavior. Defaults stamp values at create/apply time. For proxy-time dynamic lookup, use inherit_collection_config.

Quick Reference

Action	Where	Behavior
Declare expected envs	Collection → Environments tab → chip row	Auto-provisions on route join
Set base URL + default clients	Collection → Environments tab → per-env editor	Saved to the collection only
Prefill route target URL	Route create page (after picking collection)	Locked out once you type
Bulk apply to routes	Collection → Environments tab → Apply to routes	Merge or Replace, multi-select
Single-route reset	Route → Clients tab → compare row Apply	Hard replace
Single-route provision	Route → Clients tab → compare row Apply (missing env)	Creates env from defaults

Next Steps

Environment Basics

Understand the underlying environment system

Managing Clients

Learn how clients attach to route environments

Environment Workflows

Advanced patterns across environments

Audit Logs

Review every defaults operation

Key Takeaway: Declare a collection’s expected environments, base URLs, and default clients once. New routes auto-provision, existing routes stay in sync via Apply or per-route Reset, and drift never hides for long.

​Collection Environment Defaults

​What You Can Define

​Why Use Collection Defaults?

​Without Defaults

​With Defaults

​Setting Up Defaults

​1. Open the Collection’s Environments Tab

​2. Declare Expected Environments

​3. Configure Each Environment

​4. Save

​Auto-Provision on Join

​Base URL Prefill on Route Creation

​Keeping Routes in Sync

​The Sync Stats Row

​Apply to Routes Modal

Merge (recommended)

Replace all

​The Route-Level Compare Row

​Out of Sync

​Missing Env

​Merge vs Replace: When to Use Each

​Real-World Example

​Step 1: Configure the collection once

​Step 2: Add a new route

​Step 3: Add a new default client

​Step 4: A stray route

​How It Differs from Collection Variables & Inheritance

​Audit Trail

​Best Practices

​✅ Do

​❌ Don’t

​Quick Reference

​Next Steps

Environment Basics

Managing Clients

Environment Workflows

Audit Logs

Collection Environment Defaults

What You Can Define

Why Use Collection Defaults?

Without Defaults

With Defaults

Setting Up Defaults

1. Open the Collection’s Environments Tab

2. Declare Expected Environments

3. Configure Each Environment

4. Save

Auto-Provision on Join

Base URL Prefill on Route Creation

Keeping Routes in Sync

The Sync Stats Row

Apply to Routes Modal

The Route-Level Compare Row

Out of Sync

Missing Env

Merge vs Replace: When to Use Each

Real-World Example

Step 1: Configure the collection once

Step 2: Add a new route

Step 3: Add a new default client

Step 4: A stray route

How It Differs from Collection Variables & Inheritance

Audit Trail

Best Practices

✅ Do

❌ Don’t

Quick Reference

Next Steps