Using Insomnia Environment Variables to Switch API Endpoints and Tokens

Quick answer

Insomnia lets you define environment variables such as {{baseUrl}} or {{authToken}} and reuse them in request URLs, headers, bodies, and scripts. Switching the environment dropdown updates every reference at once, so you can move between dev, staging, and production without editing each request.

Worked example

1. Open the environment manager (the dropdown at the top‑right of the window) and choose Manage Environments → New Environment.
2. Create an environment named dev with two variables:
• baseUrl → https://api.dev.example.com
• authToken → dev-token-123 (toggle the Secret switch if you want the value masked in the UI).
3. Repeat the steps to create a staging environment with its own host and token.
4. Create a new GET request. In the URL field enter:

https://{{baseUrl}}/v1/resources

1. Add an Authorization header:

Bearer {{authToken}}

1. Select the dev environment from the dropdown and send the request. Insomnia expands the placeholders, producing a request to https://api.dev.example.com/v1/resources with the dev token.
2. Change the dropdown to staging and resend. The same request now points to the staging host and uses the staging token, without any further edits.

Using variables in scripts

Pre‑request and test scripts can read and write environment variables. Insomnia provides the insomnia.env object (for native scripts) and also supports the Postman‑compatible pm.environment API for users migrating collections.

// Pre‑request script – fetch a fresh token from a vault
const fresh = await getTokenFromVault(); // placeholder for your vault call
insomnia.env.set('authToken', fresh); // or pm.environment.set('authToken', fresh)

After the script runs, the {{authToken}} placeholder in the Authorization header contains the newly set value.

Limits and common mistakes

• Secret masking is UI‑only. Marking a variable as secret hides it in the editor, but the exported workspace file still stores the value in plain text unless you have an external vault integration enabled. Treat the workspace as sensitive if you rely on secret variables without a vault.
• Hard‑coded values bypass substitution. If you type a literal URL like https://api.dev.example.com instead of using {{baseUrl}}, changing environments will have no effect. Verify that every dynamic part uses the double‑curly syntax.
• Variable naming rules. Names are case‑sensitive, must start with a letter, and may contain only letters, numbers, and underscores. Spaces, hyphens, or other symbols cause the template to stay unresolved, so the literal placeholder (e.g., {{base Url}}) is sent in the request.
• Scope confusion. Variables can be defined globally, per workspace, or per environment. A workspace‑level variable with the same name as an environment variable is overridden by the environment value when that environment is active, which can lead to unexpected behavior if you rely on the workspace value.

Practical way to check the result

1. After configuring environments and the request, choose File → Export → Export Workspace.
2. Open the exported JSON file in a text editor.
3. Locate the environments array. You will see entries similar to:

{
  "name": "dev",
  "values": [
    {"key": "baseUrl", "value": "https://api.dev.example.com"},
    {"key": "authToken", "value": "dev-token-123", "type": "secret"}
  ]
}

Confirm that the values match what you entered (secret values appear as plain text here). Then, in the Insomnia UI, switch the environment dropdown and watch the request URL and headers update in the preview pane.

When to use this feature

• Moving between dev, test, and production endpoints without duplicating requests.
• Managing tokens or API keys that change frequently, especially when paired with an external vault for true encryption at rest.
• Driving data‑scenario tests where a pre‑request script sets different payloads or headers based on a variable.