Managing Multi-Environment API Workflows with Insomnia's Environment Variables

The Problem: One Request, Three Environments

You're testing an API that runs locally, in staging, and in production. Each environment has a different base URL, authentication token, and maybe feature flags. Copying requests and editing URLs by hand works for a day. Then a path changes, and you're updating five collections. Insomnia's environment variables exist to eliminate that drift.

How Environment Variables Work in Insomnia

Insomnia stores variables at the workspace level. Each workspace can have multiple environments—think development, staging, production—each holding its own key-value map. When you send a request, Insomnia resolves any {{variable_name}} placeholder against the currently selected environment. The request definition itself never changes; only the active environment does.

To set this up, open the workspace dropdown (top-left), choose Manage Environments, and create an environment named development. Add a variable baseUrl with value http://localhost:3000/api. Repeat for staging (https://staging.example.com/api) and production (https://api.example.com). Now any request using {{baseUrl}}/users will hit the correct host when you switch environments via the same dropdown.

Variable Scoping and Precedence

Insomnia resolves variables in a specific order, which matters when you have overlapping names:

1. Global — set in Preferences → Variables, available everywhere.
2. Workspace — defined in the workspace's base environment, shared across all collections in that workspace.
3. Environment — the active environment's values (development, staging, etc.) override workspace and global.
4. Collection — variables attached to a specific collection shadow everything above.
5. Request — inline variables in the request editor win last.

This cascade lets you define a global apiVersion=v1, override baseUrl per environment, and still let a single collection pin apiVersion=v2 for migration testing without touching other collections.

Worked Example: Base URL and Auth Token per Environment

Create a new request in any collection. Set the URL to {{baseUrl}}/health. In the Auth tab, choose Bearer Token and enter {{authToken}}. Now define both variables in each environment:

Environment	baseUrl	authToken
development	http://localhost:3000/api	dev-token-123
staging	https://staging.example.com/api	staging-token-456
production	https://api.example.com	prod-token-789

Switch the active environment to staging and send the request. Insomnia resolves to https://staging.example.com/api/health with header Authorization: Bearer staging-token-456. No request edits required.

Verification step: Open the request preview (the eye icon next to the Send button) to see the fully resolved URL and headers before sending. This confirms substitution works without making a network call.

Trade-offs and Limitations

• No built-in secret management. Tokens sit in plain text in the workspace file. For sensitive values, consider injecting them at runtime via a pre-request script that reads from a local .env file or OS keychain, then sets insomnia.environment.set('authToken', value).
• Environment switching is manual. There's no CLI flag to run a collection against a specific environment in headless mode without the Insomnia CLI (insomnia run supports --env). If your CI pipeline needs automated multi-environment runs, plan for the CLI workflow.
• Variable export/import quirks. Exporting a collection includes environment references but not the environment values themselves. When importing into a fresh Insomnia instance, you must recreate the environments and their variables manually or via the Insomnia API.

Putting It Into Practice

Start by auditing your current collections for hardcoded URLs and tokens. Create a baseUrl and authToken in each environment you use daily. Replace the literals with {{baseUrl}} and {{authToken}} in every request. Use the preview pane to verify resolution before your next test run. If you hit a case where a collection needs a different token format, add a collection-scoped variable to override just that one—no need to duplicate the environment.

For teams, commit the workspace file (or export the collection + environment JSON) to version control so new contributors get the same variable structure on day one. Just keep actual secrets out of git.