Using Insomnia Environment Variables and Workspace Sync to Manage Multi‑Stage APIs

Problem: Hard‑coded URLs cause environment mix‑ups

When a team maintains separate request collections for development, staging, and production, it is easy to forget to update a base URL or an API key. A single typo can send test data to a production endpoint or leak credentials. Managing these values manually also makes version‑control difficult because the request files themselves contain secrets that should not be committed.

Solution: Parameterize requests with workspace‑level environment variables

Insomnia lets you define variables at the workspace scope and then override them per environment (e.g., dev, staging, prod). A request can reference these variables with the {{variableName}} syntax. Before a request is sent, Insomnia resolves all variables, so the same collection works against any environment simply by switching the active environment.

Defining variables

Open the workspace sidebar, click “Manage Environments”, and add a variable such as baseUrl. Give it a default value (perhaps the dev URL) and then create separate environments where you override baseUrl with the staging and production URLs.

Using a variable in a request

In any request’s URL field, write {{baseUrl}}/users. When you select the dev environment, Insomnia substitutes the dev base URL; switching to prod replaces it with the production base URL. The same works for headers, query parameters, and body fields.

Version‑controlling configurations with workspace JSON export

Exporting a workspace (File → Export → Export Workspace) produces a single JSON file that contains:

• All request folders and items
• The environments array, where each environment is an object with its variables
• Workspace‑level variables (the defaults)

Because the file is plain text, you can store it in Git. Changes to environments appear as clear diffs, making it easy to review who altered a base URL or added a new secret.

Example snippet of exported JSON

{
  "name": "API Workspace",
  "environments": [
    {
      "name": "dev",
      "values": [
        {"name": "baseUrl", "value": "https://dev.api.example.com"}
      ]
    },
    {
      "name": "prod",
      "values": [
        {"name": "baseUrl", "value": "https://api.example.com"}
      ]
    }
  ],
  "resources": [
    {
      "_id": "req_123",
      "name": "Get Users",
      "url": "{{baseUrl}}/users",
      "method": "GET"
    }
  ]
}

Notice that the request’s URL uses the variable placeholder; the actual value comes from the selected environment.

Running specific environments in CI with the Insomnia CLI

The insomnia-cli tool can import a workspace and execute requests against a chosen environment. This enables a single command in a CI pipeline to run your API tests against staging or production.

Command syntax

insomnia-cli run  --env 

Where:

• is the path to the exported JSON workspace (read‑only access required)
• matches one of the name fields in the environments array
• The CLI must be installed (npm i -g @insomnia/client or equivalent) and the user executing it needs permission to read the file and make outbound HTTP requests

What to check

After the command finishes, inspect the CLI output or any test reports to confirm that the requests were sent to the expected base URL. For example, a log line might show Request URL: https://dev.api.example.com/users when --env dev is used.

Risks

If you redirect the CLI’s output to a file or log store, be careful not to inadvertently capture authorization headers or token values that are part of the request. Treat any output containing credentials as sensitive.

Trade‑off and limitation

Environment variable names must be unique within a workspace. If you accidentally define two variables with the same name (e.g., adding a duplicate baseUrl in another environment), Insomnia silently uses the later definition. This can cause confusing behavior when a teammate adds a new environment and unintentionally overrides an existing variable. To mitigate this, adopt a naming convention (such as prefixing with the environment purpose) and review the environment list before committing changes.

Additionally, syncing a workspace via Insomnia Cloud stores environments encrypted at rest, but the encryption key is tied to your cloud account. If the account is compromised, an attacker could export the workspace and read all environment secrets, including API tokens. For highly sensitive credentials, consider using an external secret manager and referencing those values only at runtime rather than storing them in the workspace.

Actionable closing

Start by exporting your current workspace, adding a baseUrl variable, and creating dev and prod environments. Commit the JSON file to your repository, then configure a CI step that runs insomnia-cli run workspace.json --env prod against your production API. Verify that the requests hit the correct endpoints and that no hard‑coded URLs remain in your collections. This approach gives you a single source of truth for API requests while keeping environment‑specific values safely separated and version‑controlled.