Using Insomnia’s Hierarchical Environments to Simplify Multi‑Environment API Testing

Problem: juggling multiple API environments

When you develop against the same API across dev, staging, and production, you often end up copying requests, hard‑coding URLs, or maintaining separate collections. Any change to a base endpoint or credential forces you to edit many places, increasing the chance of drift.

Thesis: Insomnia’s hierarchical environments let you define shared values once and override them per stage, while keeping secrets masked and enabling request chaining for multi‑step flows.

How variable scopes work

Insomnia treats variables as a hierarchy: workspace → environment → request. A variable defined at the workspace level is inherited by all environments unless an environment (or request) redefines it. At request time, the most specific value wins.

This means you can store a common base URL at the workspace level, then override baseUrl in each environment to point to https://api.dev.example.com, https://api.staging.example.com, or https://api.prod.example.com.

Secret handling

Variables can be marked as “secret”. In the UI they appear as masked characters (e.g., ********), but when the request is sent Insomnia substitutes the actual value. Secrets are still stored in the workspace file; encryption depends on your local setup or sync provider, so treat them as protected but not guaranteed end‑to‑end encrypted.

Worked example: auth token chaining

1. Create a workspace named API‑Project.
2. Add a workspace variable baseUrl with value https://api.example.com (no environment override yet).
3. Add three environments: dev, staging, prod. In each, set baseUrl to the appropriate host (e.g., https://api.dev.example.com).
4. Add a secret variable apiKey at the workspace level and give it a placeholder value.
5. Create a request GET /users with URL {{baseUrl}}/users and header Authorization: Bearer {{apiKey}}.
6. Now create a second request POST /auth/login that returns a JSON token. On the “Tests” tab, add a script like pm.environment.set('token', json.token); (Insomnia’s built‑in helper uses {{ }} syntax for environment variables).
7. Set the first request’s Authorization header to Bearer {{token}} and make sure it runs after the login request by dragging it into a folder and enabling “Run after previous request”.
8. Switch between environments in the client header; the request URL updates automatically, while the secret apiKey remains masked but is still substituted.

Trade‑offs and limitations

• Version sensitivity: Variable resolution syntax changed between Insomnia v7 and v8 (e.g., handling of undefined variables). Opening a workspace created in an older version may trigger a migration prompt or produce unexpected empty values.
• Hidden dependencies: Request chaining via environment variables creates implicit links. If you duplicate an environment or share a workspace, a missing chaining step can cause silent failures that are hard to trace.
• Secret storage: While secrets are masked in the UI, they are stored in plain text within the workspace JSON unless you enable an external vault or encrypted sync. Assume no guaranteed end‑to‑end encryption by default.

How to verify your setup

1. Open the workspace, select the dev environment, and click the “Code” tab on the GET /users request. Confirm the URL shows the dev host and the header contains the masked apiKey value.
2. Enable “View raw request” (or use a proxy like mitmproxy) to see the actual outgoing request; you should see the real apiKey value substituted.
3. Run the login request first, then the users request. Check that the Authorization header contains the token returned from login.
4. Close Insomnia, re‑open the workspace, and note any migration dialog about variable syntax. If none appears, the workspace is compatible with your current version.

Actionable closing

Start by moving shared values (base URLs, common headers, non‑secret tokens) into workspace variables. Use environment variables only for values that truly differ per stage. Mark any credentials as secrets, and verify substitution with a proxy. Finally, document any chaining steps in a README so teammates know the hidden dependencies.