Store and reuse values using variables

Variable scopes

Postman supports variables at different scopes, allowing you to tailor your processing to a variety of development, testing, and collaboration tasks. Scopes in Postman relate to the different contexts that your requests run in, and different variable scopes are suited to different tasks.

You can create a variable without a variable scope if it isn't meant to hold a default value. You can also create a variable without a scope to try out the value before adding it to a scope. Learn more about creating variables without a scope.

In order from broadest to narrowest, these scopes are: global, collection, environment, data, and local.

• Global variables enable you to access data between collections, requests, scripts, and environments. Global variables are available throughout a workspace. Since global variables have the broadest scope available in Postman, they're well-suited for testing and prototyping. In later development phases, use more specific scopes.
• Collection variables are available throughout the requests in a collection and are independent of environments. Collection variables don't change based on the selected environment. Collection variables are suitable if you're using a single environment, such as auth or URL details.
• Environment variables enable you to scope your work to different environments, such as local development versus testing or production environments. One environment can be active at a time. If you have a single environment, using collection variables can be more efficient, but environments enable you to specify role-based access levels.
• Data variables come from external CSV and JSON files to define data sets you can use when running collections with Newman or the Collection Runner. Data variables have current values, which don't persist beyond request or collection runs.
• Local variables are temporary variables that are accessed in your request scripts. Local variable values are scoped to a single request or collection run, and are no longer available when the run is complete. Local variables are suitable if you need a value to override all other variable scopes but don't want the value to persist once execution has ended.

If a variable with the same name is declared in two different scopes, the value stored in the variable with narrowest scope will be used. For example, if there is a "username" global variable and a "username" local variable, the local value is used when the request runs.

Postman stores variables as strings. If you store objects or arrays, remember to JSON.stringify() them before storing, and JSON.parse() them when you retrieve them.

Initial and current values

Each variable has an Initial value and Current value:

• Initial value is a value that's set in the element (collection, environment, or globals) where the variable is defined. This value is synced to Postman's servers and is shared with your team when you share that element. Setting an initial value can be useful when sharing elements with teammates, but note that data in an initial value is also shared with others.

  If you need to store and reuse sensitive data, it's recommended to use Postman Vault to store it as vault secrets in your local instance of Postman. Only you can access and use values associated with your vault secrets, and vault secrets aren't synced to the Postman cloud. If you want to share sensitive data with collaborators, you can store it in an environment as a secret type variable.

• Current value is used when sending a request. These are local values, and aren't synced to Postman's servers. If you change a current value, it won't persist in the original shared collection, environment, or globals.

You can persist or reset current values you've changed in variables. For more information, see sharing and persisting data.

Variable types

Beyond scope, global and environment variables can also be defined by type.

• Default type is automatically assigned to variables. This type displays as plain text and doesn't have extra properties.

• Secret type masks the initial and current values for all workspace members and can be used to prevent unintentional disclosure of sensitive data, including API secrets, passwords, tokens, and keys.

  It's recommended that you use your Postman Vault to store sensitive data, such as API keys, as vault secrets. Only you can access and use values associated with your vault secrets, and vault secrets aren't synced to the Postman cloud. If you want to share sensitive data with collaborators, you can store it in an environment as a secret type variable.

Users with Editor access on a workspace (for global variables) or environment (for environment variables) can opt to change these variables from default to secret type.

Regardless of the type you configure for a variable, Postman stores variables as strings on its servers. To learn about how Postman keeps your data safe, see Security at Postman.

To set the variable type to secret, do the following:

1. Click Environments in the sidebar, then select an environment to open the editor.

   

2. Click default next to the variable you want to change to open the dropdown, then select secret to update the variable type.

3. Click Save to confirm your changes.

Changing from secret to default variable type

You must have Editor access on a workspace (for global variables) or environment (for environment variables) to control variable types. Editors can change the variable type from secret to default at any time, and vice versa. When you change a variable's type from secret back to default, you must confirm by selecting Change type.

Viewing and changing secret variable values

All workspace members can view a secret variable's initial and current values by clicking next to the variable.

Editors can change a variable's initial values, which are shared with collaborators, by clicking next to the variable, then selecting the initial value. All collaborators can change a variable's current values by clicking , then selecting the current value.

Defining variables

You can define variables in the following ways:

• Define a value for a variable without a scope, then add the variable to a scope.
• Define a variable directly in the global, environment, or collection scope.
• Select a value in the URL bar or the Body, Params, Headers, or Authorization tabs.

Learn more about variable scopes in Postman.

To define variables at any scope in the request builder, do the following:

1. Select the data you need, for example in the address, parameters, headers, or body.

2. Right-click the selection and click Set as variable.

   

3. Click Set as new variable.

   

4. Enter a Name, confirm the Value is correct, and select a Scope. Click Set Variable.

   

Remember to delete variables you're no longer using.

Setting values for variables without a scope

Variables without a variable scope are useful for trying out the value before adding the variable to a scope. This is also useful for sending data with requests that isn't meant to hold a default value. For example, a variable without a scope might send user-specific information that changes each time you send the request. Variables without a scope also enable you to create a placeholder variable to share with your API consumers, without having to define the variable at a specific scope.

In the request builder, you can create a variable without adding it to a variable scope. The value you enter for this variable is stored locally and is only available in the request it's set in. When you click Variables, the variable isn't associated with a scope (highlighted by color) in the variables pane under Variables in request.

To create a variable from the request builder, use double curly braces ("{{" and "}}") to reference a variable that doesn't exist or isn't available from the request. For example, enter "{{username}}" to create a username variable that doesn't have a scope.

To set a value for a variable without a scope, hover over it, click the text box, then enter a value. You can also click Variables in the workbench to open the variables pane. Click Enter value next to the variable, then enter a value.

You can use pm.variables.get(variableName) to access variables without a scope in scripts. Learn more about using variables in scripts.

Values for variables without a scope are stored locally in a request until you close its tab or sign out of Postman. When you open the request again, the variable's value will be empty. If you'd like to store and reuse the value in your requests, you can add the variable and its value to a scope.

You can also create a vault secret without adding it to your Postman Vault. Open your Postman Vault, then use the "{{vault:secret-name}}" syntax. When you're ready, you can add the vault secret to your Postman Vault. Learn how to create and add a vault secret from the request builder.

Adding variables to a scope

From a Postman element, such as a request or collection, you can create a variable and add it to a specific variable scope to reuse it across your requests. You can also add a variable without a scope to a specific variable scope in your team. From the element, you can add a current value that's stored locally for the variable.

You need Editor access to an environment or collection to add variables to it.

Use double curly braces ("{{" and "}}") to reference a variable that doesn't exist or isn't available from the element. Hover over the reference to the variable, click the text box, then enter a current value if you haven't already. Select the Add to dropdown list, then select the scope you'd like to add the variable to.

You can define variables at any scope from the Authorization tab. Select the Auth Type dropdown list, select an authorization, then enter a current value in a field that holds sensitive data, such as a password or token. Hover over Sensitive value, click Set as Variable, enter a name for the variable, then select the scope you'd like to add it to.

You can also click Variables in the workbench to view the variables and vault secrets used in your request. Click the text box, enter a current value for the variable without a scope, click Add to, then select the scope you'd like to add it to.

You can also choose to add sensitive data as a vault secret in your Postman Vault. To add it as a vault secret in your Postman Vault, first open your Postman Vault.

The environment you want to add a variable to must be active in the environment selector. If an environment isn't active, you can add a variable to an environment using one of the following options in the dropdown list:

• Select an existing environment - Click Select, then choose an environment to make it active. The variable is added to the selected environment.
• Create a new environment - Click Create One, enter a name for the environment, then select Create. The variable is created and added to the new environment.

If the variable without a scope has the "vault:" prefix (for example, "vault:postman-api-key"), you can only add it to your Postman Vault as a vault secret.

To add an initial value to a variable that you can shared with collaborators, learn how to edit variables directly in the global, environment, and collection scope.

Setting response body values as variables

Setting response body values as variables is only available in the Postman desktop app.

To set the values for existing global and environment variables to values from a request's response body, do the following:

1. (Optional) If you're setting the value for an environment variable, select the variable's environment from the dropdown list located in the top right of the workbench.

2. In the response, highlight the variable text, then right-click it.

3. Select the relevant scope (environment or global), then select the name of the variable.

   

Defining global variables

To view global variables, do the following:

1. Click Environments in the sidebar.
2. Click Globals.

To add a new global variable, do the following:

1. Click the Variable text box and enter a variable name.
2. Select a Type.
3. Add an Initial value and a Current value.
4. Click Save to confirm your changes.

To edit an existing global variable, do the following:

1. Change the desired variable value.
2. Click Save to confirm your changes.

Learn about defining global variables in scripts.

You can also view and edit the current value of a global variable directly from a Postman element. Learn more about viewing and editing variables in an element.

Downloading global environments

To download global variables as JSON, do the following:

1. Click Environments in the sidebar.
2. Click Globals.
3. Click Export.
4. Choose where to save the file, then click Save.

Defining environment variables

To view environment variables, click Environments in the sidebar and select the environment you want to view.

To add a new environment variable, do the following:

1. Click the text box, then enter a name for the variable.
2. Select a Type for the new variable.
3. Add an Initial value and a Current value.
4. Click Save to confirm your changes.

To edit an existing environment variable, do the following:

1. Change the desired variable value.
2. Click Save to confirm your changes.

You can add and edit variables if you have Editor access to an environment. If you have Viewer access, you're restricted to updating the current value of existing variables. Any variables you edit are available to you, but not to collaborators in your workspace. Learn about working with environments in your team and defining environment variables in scripts.

You can also view and edit the current value of an environment variable directly from a Postman element. Learn more about viewing and editing variables in an element.

Defining collection variables

You can add collection variables when you create the collection or at any time after that.

To create or edit an existing collection's variable, do the following:

1. Click Collections in the sidebar.
2. Select a collection, and then click the Variables tab.

With Editor access to a collection, you can add new collection variables, update initial values, and persist values. You can also define collection variables in scripts. If you have Viewer access to a collection, you can only update the current value of existing collection variables. Learn how to request Editor access to a collection.

You can also view and edit the current value of a collection variable directly from a collection, folder, or request. Learn more about viewing and editing variables in an element.

Defining variables in scripts

You can set variables and vault secrets programmatically in your request scripts.

Method	Use case	Example
pm.globals	Define a global variable.	pm.globals.set("variable_key", "variable_value");
pm.collectionVariables	Define a collection variable.	pm.collectionVariables.set("variable_key", "variable_value");
pm.environment	Define an environment variable in the current environment.	pm.environment.set("variable_key", "variable_value");
pm.variables	Define a local variable.	pm.variables.set("variable_key", "variable_value");
pm.vault	Define a vault secret in your Postman Vault.	await pm.vault.set("secret_key", "secret_value");
unset	Use unset to remove a variable.	pm.environment.unset("variable_key");

If you don't have Editor access to an environment, your script code will affect the current value but won't be synced or shared with your team.

Make sure you enable scripts to access your vault secrets. Otherwise, you'll receive an error in the Postman Console, and any code that comes after the method won't run. Also, you must use the await operator before each pm.vault method for it to run in your script.

For instructions on how to use variables in pre-request or post-response scripts, see Using variables in scripts.

Specifying variable detail

You can add and edit variables at any time. A variable requires a name. You can set an initial value or set one later, including from scripts. Use the variable checkbox to turn it on or off.

Initial values are shared when you share a collection or environment. Current values are local and not synced or shared. See Initial and current values for more on local versus synced variables.

Using variables

You can use double curly braces ("{{" and "}}") to reference variables throughout Postman. For example, to reference a "username" variable in your request's authorization settings, use the following syntax:

{{username}}

When you run a request, Postman resolves the variable and replaces it with its current value. For example, you could have a request URL referencing a variable:

https://postman-echo.com/get?customer_id={{cust_id}}

Postman sends the value stored for the "cust_id" variable when the request runs. If "cust_id" has a "3" value, the request is sent to the following URL with the query parameter:

https://postman-echo.com/get?customer_id=3

If you want to access a variable from within a request body, wrap its reference in double-quotes:

{ "customer_id" : "{{cust_id}}" }

You can use variables in request URLs, parameters, headers, authorization, body, and header presets.

When you hover over a variable, Postman shows its value and its scope. As you add variables to your requests, Postman displays any existing variables.

The prompt indicates the current value, scope (highlighted by color), and OVERRIDDEN status where relevant.

If a variable doesn't have a current value, Postman highlights it in red. Also, a red exclamation point displays on Variables in the upper-right of the workbench. For information on how to fix this, see Fixing empty variables.

Using dynamic variables

Postman provides dynamic variables you can use in your requests. Examples of dynamic variables include:

• {{$guid}} - A v4-style GUID.
• {{$timestamp}} - The current Unix timestamp, in seconds.
• {{$randomInt}} - A random integer between 0 and 1000.

See the Use dynamic variables to return randomly generated data section for a full list.

Using variables in scripts

You can retrieve the current value of a variable in your scripts using the object representing the scope level and the .get method:

//access a variable at any scope including local
pm.variables.get("variable_key");
//access a global variable
pm.globals.get("variable_key");
//access a collection variable
pm.collectionVariables.get("variable_key");
//access an environment variable
pm.environment.get("variable_key");
//access a vault secret
await pm.vault.get("secret_key")

Using pm.variables.get() to access variables in your scripts gives you the option to change variable scope without affecting your script functionality. This method returns the variable that has the highest precedence (or narrowest scope).

Postman doesn't support using pm.variables to access and manipulate vault secrets.

To use dynamic variables in pre-request or post-response scripts, use pm.variables.replaceIn(). For example:

pm.variables.replaceIn('{{$randomFirstName}}')

See Process data and script workflows using Postman JavaScript objects for more details about scripting with variables.

Logging variables

You can log variable values to the Postman Console while your requests run. Use the following syntax in your script to log the value of a variable:

console.log(pm.variables.get("variable_key"));

To view the results, click Console in the footer. You can also access the Console by selecting View > Show Postman Console.

Using data variables

The Collection Runner lets you import a CSV or a JSON file and use the values from the data file inside requests and scripts. You can't set a data variable inside Postman because it's pulled from the data file, but you can access data variables inside scripts, for example using pm.iterationData.get("variable_name").

For more details, see working with data files and the Postman JavaScript reference.

Sharing and persisting data

When you edit global, collection, and environment variables in Postman, there's a Current value that you can choose to Persist or Reset for individual variables. You can also select Persist All or Reset All to apply this setting to all variables. These enable you to control what happens within your local instance of Postman, independently of how the data is synced with anyone sharing your workspace, requests, collections, and environments.

When you create or edit a variable, you can enter both an initial and a current value. When you create a new variable in Postman, if you leave the current value empty, it autofills with the initial value. If you specify a current value, it's local to your instance. The Persist option pushes your current value to the shared data, updating the initial value to match the current value.

If you don't have Editor access to an environment, you can't edit the initial value of an environment variable. You can edit the current value, and your edit won't be visible to anyone sharing your workspace.

Using Persist makes your current value sync with Postman's servers and be reflected for anyone sharing your collection or environment. To reset your current local values to reflect the initial shared values, use Reset.

To persist individual values, do the following:

1. Hover over a variable's current value.
2. Click View more actions next to the value.
3. Click Persist.

Your local session in Postman can use values that are transient and visible to you, but aren't synced or shared with your team. This lets you develop and test using private credentials or experimental values, without risk of exposing these details or affecting others on your team.

For example, your team could have a shared API key and individual API keys. You could do experimental development work locally using your personal key, but use the shared key for team collaboration. Similarly, you could have a variable that represents exploratory work you're doing locally but aren't ready to share with the team. You can later choose to persist the local data so that others on your team can also access it.

You can edit a current value from an element, such as a request. Click Variables in the workbench to update the current value in the variables pane. Learn more about viewing and editing variables in an element.

For more information on working with variables as a team, see Work with environments as a team in Postman.

Local and data variables have current values, which don't persist beyond request or collection runs.

Viewing and editing variables in an element

Use the variables pane to view and edit the variables and vault secrets a Postman element uses and can access. With the variables pane, you can edit your variables and vault secrets in one location. You won't have to locate and update every variable in each scope and vault secret in your Postman Vault.

To access the variables pane, open a Postman element, then click Variables in the upper-right of the workbench. The variables pane opens on the right where you can view the following:

• Variables in request - View and edit the current value of variables and vault secrets referenced in a request. This also shows variables without a scope that are referenced in your request.
• All variables - View and edit the current value of variables and vault secrets that are available from your Postman elements, such as a request or collection. For example, if you have a request open, this might show variables defined in the active environment that you could choose to reference in the request.

You can also hover over a reference to a variable or vault secret, then click Variables in request or All variables to open the variables pane.

Secret type variables stored in the active environment or globally in the workspace are masked by default.

Variables used in a request

To view variables and vault secrets used in a request, click Variables in the workbench to open the variables pane. The variables under Variables in request are defined at the environment, collection, or global variable scopes and show the current value. This also shows vault secrets stored in your Postman Vault.

You can edit the current value of a variable or vault secret that's referenced in a request. Open the variables pane, delete the existing value next to a variable or vault secret, then enter a new value.

You can also hover over the reference to the variable or vault secret, delete the existing value, then enter a new value.

If the request auth is set to Inherit auth from parent, you can view variables and vault secrets in the variables pane that are used in the Authorization tab of the request's parent collection or folder. Learn more about inheriting authorization from a parent element.

Access variables from an element

Under All variables in the variables pane, you can view and update variables and vault secrets that are available from your Postman elements. For requests that reference a variable or vault secret, select All variables to display all variables and vault secrets a request can access. Variables and vault secrets in this section can be referenced and resolved in the element that's open.

You can edit the current value of a variable or vault secret that's available from an element. Click Variables to open the variables pane, delete the existing value next to a variable or vault secret, then enter a new value.

You can also take the following actions to update the variables and vault secrets from the variables pane:

• If an environment isn't selected, click Select environment to choose an environment from the environment selector.
• If there are no variables defined in the selected environment, associated collection, or globally in the workspace, click Add to open it in a new tab.
• If there are no vault secrets defined in your Postman vault, click Add secrets to open your Postman Vault in a new tab.

Fixing empty variables

An empty variable is a variable that's referenced in a request but doesn't have a current value. For example, Postman expects to find a current value for "{{cust_id}}" in the https://postman-echo.com/get?customer_id={{cust_id}} request. If Postman doesn't find a current value for the variable, it's flagged as an empty variable and the request may fail when you send it.

A variable can be empty for the following reasons:

• The variable was created but changes weren't saved.
• The environment that has the variable isn't active.
• The variable is turned off in the respective collection, active environment, or globals.
• The variable doesn't have a scope, and a value hasn't been added to it.

A vault secret can also be empty if it's missing a value and is referenced in a request. Learn how to fix empty vault secrets.

When you're working on an API request, Postman highlights empty variables in the URL builder and in the Params, Authorization, and Headers tabs. Postman highlights empty variable text in red. If your request has an empty variable, a red exclamation point displays on Variables in the upper right of the workbench.

To view empty variables referenced in a request, do the following:

1. Open a request with empty variables, then click Variables.
2. Under Variables in request, review the variables without values.

To check if the variable exists and is available from the request, do the following:

1. Select the collection in the sidebar that's associated with the request, then click the Variables tab. You can also click Environments in the sidebar, then select Globals or one of the environments.
2. Turn on the variable, make the necessary changes to the value of the variable, or make the correct environment active.
3. Click Save to confirm your changes.

Learn more about viewing and editing variables in an element.

From a request, you can set local variables programmatically in a pre-request script using pm.variables.set. When the variable is also referenced in the request, it'll display as Resolved via script in the variables pane. Environment, global, and collection variables set programmatically (for example, pm.environment.set) are saved for later use at their respective scope. If you experience issues referencing a variable set programmatically, debug your requests with the Postman Console.