Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 30 ยท Organizing Work

Environments and variables

Understand Postman variable scopes, how {{variable}} names are resolved, initial versus current values, environments for dev and prod, and how to keep secrets safe.

Hard-coded values are the enemy of reusable tests. If https://staging.example.com is typed into forty requests, moving to production means forty edits, and one forgotten edit means a test run against the wrong server. Postman solves this with variables: you write {{baseUrl}} wherever the value appears, and Postman substitutes the real text just before sending.

Variables come in several scopes, and an environment is the most useful one: a named set of variables such as "Local", "Staging" or "Production" that you switch with one click. In this lesson you will learn the scopes, the order in which they win, the difference between initial and current values, and how to treat secrets. A runnable stand-in implements the resolution rules so you can see them work.

The Postman app cannot run here, so UI steps are read-only. The resolver in the examples is a small stand-in written in plain JavaScript that follows the same rules.

Five places a variable can live

Global Visible in the whole workspace.
Collection Shared by one collection.
Environment Local, Staging, Production.
Data One row of a CSV or JSON file in a run.

A fifth scope, local, exists only during one run.

1 / 2

Using a variable

Wrap a name in double curly braces anywhere text is accepted: URL, query params, headers, the body, authorization fields, even other variables.

HTTP
GET {{baseUrl}}/orders/{{orderId}}
Authorization: Bearer {{token}}

Postman highlights a known variable in orange and an unknown one in red. Hover to see its scope and value. If a variable cannot be found, Postman sends the literal text {{orderId}}, which usually produces a confusing 404 or 400; a red variable is the first thing to check when a request fails strangely.

The scopes

Scope Where it lives Typical use
Global Workspace-wide Rare; quick experiments, values shared across collections
Collection One collection Constants of one API, such as a version number
Environment One selected environment Base URL, credentials, anything that differs per server
Data A row from a CSV/JSON file used in the Collection Runner Test inputs (see The Collection Runner)
Local A single request or run, set only by scripts Temporary values that should vanish afterwards

Precedence. When the same name exists in several scopes, the narrowest scope wins: local, then data, then environment, then collection, then global. This is useful (an environment can override a collection default) and dangerous (a forgotten global with the same name can shadow what you expected). Prefer unique, descriptive names such as orderId rather than id.

Environments

An environment is one set of variables. Create it from Environments in the sidebar, name it, add variables, and choose it in the dropdown at the top right of the workspace. A typical trio:

Variable Local Staging Production
baseUrl http://localhost:3000 https://staging.example.com https://api.example.com
username dev qa-bot smoke-test
token (empty, filled by login) (empty) (empty)

The requests stay identical; only the selected environment changes. This is also how the same collection is run in a CI pipeline against a different server (see Newman, the CLI and CI/CD).

Initial value and current value

Every environment or global variable has two values, and this trips up almost everyone once.

  • Initial value: stored in the shared workspace. When you sync or share, everyone with access sees it.
  • Current value: stays on your machine only and is what requests actually use. It is not synced.

If you leave the current value empty, Postman uses the initial value. When a script calls pm.environment.set("token", ...), it changes the current value, which is why login tokens never leak into shared data.

The consequence for secrets is clear: put placeholder text (or nothing) in the initial value and the real secret in the current value. For stronger protection, mark a variable's type as secret, which masks it on screen, and consider a vault or CI-provided secrets for anything that matters. Remember that exports and shared workspaces may include initial values (see Collections, folders and requests for the export warning).

Dynamic variables

Postman also ships built-in dynamic variables that produce fresh values on every send. Examples are {{$guid}} (a random UUID), {{$timestamp}} (current Unix time in seconds) and {{$randomInt}} (a random integer). They are handy for creating unique test data, such as a new email address every run.

Variables inside variables

A value may contain another variable, and Postman resolves it too. If host is staging.example.com and baseUrl is https://{{host}}/v1, then {{baseUrl}}/orders becomes https://staging.example.com/v1/orders. Keep the nesting shallow; deep chains are hard to debug.

Building a resolver

The stand-in below implements the rules you just learned: scopes with precedence, nested variables, a depth limit so a variable that refers to itself cannot loop forever, and detection of unresolved names.

JS A tiny variable resolver

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the third line: {{userId}} exists nowhere, so it stays as literal text, exactly what Postman would send. The final lines show a local value overriding the environment, and the loop guard.

Initial versus current in code

The second stand-in models the two values of one variable, shows which one is used, and prints what would be synced and what would stay private.

JS Initial value versus current value

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real pm.environment.set call behaves like the helper in the stand-in; scripts are covered in Pre-request scripts.

Working with variables in scripts

In a script you will meet these calls (they run only inside Postman, shown here read-only):

JavaScript
pm.environment.set("orderId", "1001");        // environment scope
pm.environment.get("orderId");
pm.collectionVariables.set("version", "v1");  // collection scope
pm.globals.set("team", "qa");                 // global scope
pm.variables.set("temp", "x");                // local scope
pm.variables.get("orderId");                  // resolves through ALL scopes

pm.variables.get follows the precedence order, whereas the scope-specific getters read one scope only. Use the scope-specific form when you mean a particular place, and pm.variables.get when you want "whatever the request would use".

Practical advice

  • One environment per server, with identical variable names in each.
  • Name variables for what they mean, not their value: baseUrl, not stagingUrl.
  • Never store production credentials in a shared workspace.
  • Clean up after tests that create environment variables; stale orderId values cause baffling failures.
  • Check the red highlight and the Console before blaming the server.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A variable named baseUrl exists in the collection scope and in the selected environment. Which value is used?

    Precedence runs local, data, environment, collection, global, so the environment value overrides the collection value.
  2. 2. Which value of an environment variable is shared when you sync or share a workspace?

    The initial value is stored in the shared workspace; the current value stays on your own machine.
  3. 3. A request URL contains {{orderId}} but no scope defines it. What does Postman send?

    Unresolved variables stay as literal text, which is why a red variable usually explains a strange 404 or 400.
  4. 4. Where does pm.environment.set("token", value) write?

    Scripts update the current value, so tokens obtained at runtime are not synced to other people.

Summary

  • {{name}} is replaced just before a request is sent; unknown names stay as literal text.
  • Scopes are global, collection, environment, data and local; the narrowest scope wins.
  • An environment holds one server's settings; switching it retargets every request.
  • Initial values are shared, current values are private and used first: keep real secrets in current values.
  • Scripts set variables with pm.environment.set and friends; pm.variables.get resolves through all scopes.

Next: Saved examples, documentation and mock servers.