Variables and environments

A variable is a named value you write once and use in many requests. Put the server address in a variable called baseUrl, and moving every request from your laptop to staging is one click.

Use a variable

Write the variable's name between double curly braces, anywhere in a request:

{{baseUrl}}/users/{{userId}}

When you send, each placeholder is replaced by the variable's value. With baseUrl set to https://api.example.com and userId set to 42, the request goes to:

https://api.example.com/users/42

Variables are filled in here:

Place	Example
URL	{{baseUrl}}/orders
Path variable values	:id = {{orderId}}
Query param names and values	limit = {{pageSize}}
Header names and values	X-Tenant = {{tenant}}
Body: JSON, text, XML, form fields, GraphQL, file paths	{"email": "{{email}}"}
Auth fields	Token = {{token}}

A name that no scope defines is left as written. If a request goes out with {{baseUrl}} still in it, the variable is missing, switched off, or the wrong environment is selected.

Names that start with $, such as {{$guid}}, are dynamic variables: the app generates a new value each time.

Scopes

Variables live in scopes. A scope decides which requests can see a variable.

Scope	Who sees it	Where you edit it
Globals	Every request in every collection	Envs on the rail, then Globals
Collection	Every request saved in that collection	The collection's … menu, Variables
Environment	Every request, while that environment is selected	Envs on the rail, then the pencil on the environment
Data	Requests in a runner iteration: the current row of the data file	Data files
Local	One send: values a script sets with pm.variables.set	Scripts

Precedence

When the same name exists in more than one scope, the highest scope wins. From lowest to highest:

Globals < Collection < Environment < Data < Local

Example: baseUrl is https://api.example.com in the collection and http://localhost:8080 in the selected environment. Requests use http://localhost:8080. Select No environment and they use the collection's value again.

The Globals editor shows this order at the top, and marks a global that a higher scope hides with Overridden by and the name of the scope.

Environments

An environment is a named set of variables for one place you test: local, staging, production. Only one is active at a time.

Create an environment

1. Select Envs on the rail.

2. Select +, Create an environment, at the top of the panel. With no environments yet, select New environment.

3. Type a name, such as Local, and select OK.

   The variable editor opens.

4. Select Add variable, type the name under Variable and the value under Initial value.

   Variable	Initial value
   baseUrl	http://localhost:8080

5. Select Done.

The first environment you create becomes the active one. Changes are saved as you type.

Choose the name with care: version 1.4.0 has no command to rename an environment.

Switch environment

Use the environment picker at the top right of the window. It shows the active environment, or No environment. Select it and choose another. Manage environments opens the Envs panel.

You can also click an environment in the Envs panel. The active one has a filled circle.

Selecting No environment leaves only Globals and collection variables.

Edit or delete an environment

In the Envs panel, select the pencil on the environment's row to open its variables.

To delete the environment, select the bin icon at the top of that dialog.

WARNING

The bin deletes the environment and its variables at once, without asking. Export first if you may need them.

Collection variables

Collection variables belong to one collection and are seen only by its requests. They suit values that describe the API itself, such as a default baseUrl or an API version.

1. In Collections, open the … menu on the collection.

2. Select Variables.

3. Add or change variables, then select Done.

The same editor is on the Variables tab of the collection's Auth, scripts and docs dialog.

A request that is not saved in a collection sees no collection variables.

Globals

Globals are seen by every request, whatever the collection or environment. They have the lowest precedence, so any other scope can override them.

Open them from the Envs panel: select the Globals row under the list of environments.

The variable editor

Environments, collection variables and Globals use the same editor.

Column	Meaning
Tick box	Ticked variables are used. Untick one to switch it off without deleting it.
Variable	The name. Use it in a request as {{name}}.
Initial value	The shared starting value. It is saved with exports.
Current value	Your local value, used when you send. Empty means "use the initial value", which then shows greyed out.
Type	Default shows the value as typed. Secret hides it.
Menu (three dots)	Reset, Persist, Secret, Description…, Delete

Above the rows:

Control	What it does
Add variable	Adds an empty row at the end
Filter variables	Shows only the variables whose name, description or value contains the text. Secret values are never searched.
Reset all	Clears every current value, after asking
Persist all	Copies every current value over its initial value, after asking

With a filter active, Reset all and Persist all act on the matching variables only.

Initial and current values

Each variable has two values.

	Initial value	Current value
Used when sending	Only when the current value is empty	Yes
Included in exports	Yes	No, it stays on this device
Written by scripts and captures	No	Yes
Good for	Defaults that are safe to share	Your own tokens, passwords and temporary values

This split lets you share a collection or environment without sharing your secrets. Put a placeholder or nothing in Initial value and your real token in Current value.

Example:

Variable	Initial value	Current value	Requests use
baseUrl	https://api.example.com		https://api.example.com
token		eyJhbGci…	eyJhbGci…

Reset and persist

Action	What it does
Reset	Clears the current value, so requests use the initial value again. The initial value does not change.
Persist	Copies the current value into the initial value, the shared and exported one, and clears the current value.

Both are in a variable's menu. Reset all and Persist all do the same for every variable in the editor.

WARNING

Persist on a token makes it the initial value, so it is included the next time you export. Reset or clear such variables before sharing a file.

Values written for you

Captures and scripts write current values, never initial ones.

• A script names its scope: pm.environment.set, pm.collectionVariables.set or pm.globals.set. A name that does not exist yet is created with an empty initial value.
• A capture goes to the active environment. With No environment selected, it goes to the collection's variables.
• With No environment selected and a request that is not in a collection, captured values are kept only until you close the app.

Secret variables

Set a variable's Type to Secret for tokens, passwords and keys.

A secret variable's value is hidden:

• in the variable editor, where both values show as dots until you select the eye on that row
• in the Console
• in generated collection docs and request docs
• in apiworkbench-cli reports

Load-test reports are not masked: review one before you share it.

It works in requests like any other variable.

Exports are not masked

Exported files are plain text. A secret variable's initial value is written to the file as it is; a Postman environment export only adds a flag marking it as secret. Clear secret initial values, or keep secrets in current values and leave Include current values off, before you share a file. See Export and share.

DANGER

Secret means hidden, not encrypted. Secret values are stored as plain text in the app's data files on your device, protected by your operating system account like your other files. Do not treat Secret as a safe place for credentials on a shared computer.

Describe a variable

Open a variable's menu and select Description… to add a note, such as Base URL of the staging API. The note shows under the variable and is saved with it.

Postman compatibility

Scopes, precedence, initial and current values and secret variables work as they do in Postman. Imported environments and globals keep their values and secret flags. See Import from Postman.

Troubleshooting

The request is sent with the placeholder still in it

The name is not defined in any scope the request can see. Check:

• the environment picker shows the environment you expect
• the variable's tick box is ticked
• the spelling matches exactly, including upper and lower case
• for a collection variable, the request is saved in that collection

A variable has the wrong value

A higher scope defines the same name, or a current value hides the initial one. Look at Current value in the editor, and at the same name in the environment, collection and Globals. Reset removes a stale current value.

Check yourself

QuizVariables and environments

Question 1 of 6

baseUrl is set in two places, and the Local environment is selected. Where does {{baseUrl}}/orders go?

Collection:          baseUrl = https://api.example.com
Environment (Local): baseUrl = http://localhost:8080

Score: 0

Next steps

• Dynamic variables
• Captures
• Data files
• Authorization