Managing environments

An environment is a set of variables you can use in your Postman requests. You can use environments to group related sets of values together and manage access to shared Postman data if you are working as part of a team.

Environments quick start

A typical use of environments could work as follows:

  • You have a production API and a development API, at different locations.
  • You use two environments, one for development and one for production.
  • Each environment includes a variable to store the base URL.
  • Each request in your collection refers to the variable in the URL field.
  • You toggle between environments when running your requests to test them against either the development or the production environment.
  • Within your organization, you could have a team that only has access to the development environment, and individual team members with edit vs readonly access to specific environments.

You can use the current value of your environment variables to ensure that sensitive data values such as credentials are not accidentally shared. By using environments rather than global variables, you can control visibility of your data values within your workspace and team.


Creating environments

You will see the selected environment status at the top-right of Postman, with any active environment selected in the drop-down. In Environments on the left you can access all environments, and click the check-mark button to make an environment active. Select an environment to open it for editing in a tab.


To the right next to the drop-down you will also see the Environment quick look (eye) button. The quick look lists variables for the active environment, and any global variables you have declared (or that are shared via your workspace).

Environment quick look

To create a new environment, select Environments on the left and click the + plus button.

Manage environments

Enter a name for your environment, and initialize it with any variables you need—you can alternatively specify variables for the environment later.

Add Environment

Click Save to save any environment variables you have added.

Adding environment variables

You can add variables to an active (currently selected) environment by opening the environment from the left of Postman and editing in the tab that opens.

Edit environment

Edit the variable names and values inline, or use the X button to delete a variable. Enter the name and values for a new variable on a new line. Save when your changes are complete.

Alternatively, open the environment quick look (the eye button at the top right) and edit inline.

Edit Environment

If you are working with environment variables as part of a team, you will only be able to change initial values if you have edit access to the environment. You can access all variables in environments shared with you, but may have readonly access to initial values if you have viewer role.

Enter a name for your variable, and specify Initial and Current values for it—by default the current value will copy the initial value.

  • The Initial Value is synced to your account via the Postman servers and shared with any collaborators who have access to the environment.
  • The Current Value is local to your Postman app, and is never synced to your account or shared with your team—unless you choose to persist it.

To update the synced variable with your local value, set the initial value to the current value by selecting Three dots icon to the right of the variable row and choosing Persist. To reset your local (current) value with the synced value shared with your workspace / collaborators, click Reset. You can persist or reset all values in the environment using Persist All and Reset All.

You can also mask environment variables by changing their type to secret.

Accessing environments

You can access your environment variables from the Postman UI and from your request elements, including the URL, parameters, body data, and test scripts.

To see all of your environments, click Environments on the left of Postman.


Here you can add, share, duplicate, download, manage access, delete, and remove a shared environment from a workspace. You can also access your global variables by clicking Globals.

To view the variables in an environment, click its name. You can edit, add, and remove variables from the environment here.

Edit environment

Selecting an active environment

To use the variables in an environment, select it from the drop-down list at the top right of Postman.

Environment Dropdown

To check a variable value at a glance, use the quick look (eye button).

When you have an environment selected in the drop-down, Postman will treat it as the active environment, and will run all requests against that environment (if your requests reference environment variables).

To use an environment variable value in a request, reference it by name, surrounded with double curly braces:


You can use the same variable notation in request URLs, parameters, headers, and body data.

Environment var reference

Hover over a variable reference to see its current value.

If more than one variable with the same name is available to a request, Postman will use the value from the variable with narrowest scope. This means that if you have an environment variable with the same name as a collection or global variable, Postman will use the environment variable, but local and data variable values will supersede environment values. The value of any overridden variables will display with a strikethrough. Overridden value

You can access current environment variable values in your Pre-request and Tests code.


You can publish environments with your API documentation and the Run in Postman button.

Editing environment variables

You can edit variables either by opening an environment from Environments on the left, or by opening the environment quick look (eye button) at the top right of Postman, and clicking Edit.

You will only be able to edit environments where you have editor access.

Edit environment

Edit the environment name, or the names and values of your variables, bearing in mind that Initial Values will be synced with your Postman account and shared with any collaborators who have access to the environment. Click Save when your edits are complete.

Viewer role on environment

If you have viewer access to an environment, you will see a padlock icon next to the name to indicate that it is readonly, and you will only be able to edit the current value, which is visible only to you and not synced with your Postman account or workspace. To edit initial values you will need to Request Access.

You can edit current values for variables in an active (currently selected) environment directly via the environment quick look. Click the pencil icon to edit your chosen value.

Edit Environment

You can also update environment variable values from your test scripts.

Setting environment variables from scripts

Your Pre-request and Tests scripts can update environment variable values.

Use pm.environment to set an environment variable in the active (currently selected) environment:

pm.environment.set("variable_key", "variable_value");

You can only create new variables from a script in an environment that you have edit access to. If you update or unset a value in a script with viewer access to the environment, that change will only be visible to you and not shared with your team.

If you use scripts to set environment variable values, these will be reflected for all requests referencing the variables. For example, you can use environments in conjunction with the collection runner and monitors to share updated values throughout a run for a series of requests as well as after it completes.

Working with environments as a team

You can use environments to collaborate on your API development and testing processes with team members. Environments allow you to access shared resources and to configure visibility of restricted data such as specific server locations, and sensitive information like API keys.

In a shared workspace, any global variables you create and update will be available to others in the workspace. You can use the Current Value of global variables to restrict certain values from collaborators, but by default the Initial Value of a global variable is generally accessible throughout the workspace.

You can move environments to shared workspaces to collaborate with your team.

You must be an editor on an environment, or the workspace admin, to move an environment to another workspace.

Navigate to the environment you'd like to share in the left sidebar, select it, then select Three dots icon > Move.

Use the search bar to find the workspace you'd like to move the environment to, or filter by workspace visibility by selecting the icon to the right of the search bar.

You can share environments to personal, private, team, and public workspaces that you have access to. Shared private, team, and public workspaces allow you to collaborate with others.

You cannot move environments from team, private, or public workspaces to a personal workspace.

Refer to Roles and permissions for information on workspace access control within your team.

Select the workspace, then Move Environment.

Move environment

Note that monitors, mock servers, and integrations in the original workspace that are using the environment may no longer work and will need to be re-configured in the new workspace. Collections and APIs that use the environment must be moved separately.

You can manage roles on an environment by navigating to it in the left sidebar, selecting it, then selecting Three dots icon > Manage Roles.

Manage roles environment

You can also remove a shared environment from a workspace by selecting Three dots icon next to the environment name and choosing Move to move it to a different workspace or Delete to delete it entirely.

To export an environment, select it and click Three dots icon in the upper right > Export.

Export environment

Managing environment roles

If you use personal credentials in your requests and the requests are pulling these from a shared environment (for example a variable storing an API secret value), you can restrict visibility of your credentials by only storing them in the current value of the variable. If you are managing an environment that's shared across a team, you can restrict edit access so that most of your team only has viewer role on the environment, which prevents them from accidentally updating the shared value and leaking credentials. Similarly, you can prevent accidental changes to values by restricting the number of team members who have edit access to your environment.

In order to effectively leverage environments to preserve security and minimize the risk of accidental changes to variables, group your variables into environments you want to share as a coherent set, and then configure each user role so that access is only granted where it's required, and that you can source any accidental changes.

When you open an environment without edit access you will see an option to Request Access, and will only be able to edit Current Values.

Viewer role on environment

Default access allows collaborators to use variable values in their requests, but they can only edit the initial value of a variable if they have edit access to the environment as a whole.

Using an environment in viewer role

If you have view access to an environment, you will be able to access the value of the variables to use them in your requests, but will not be able to update the Initial Value, which is shared with your team. You can update the Current Value, but this is not shared with anyone on your team or synced with your Postman account.

If you are using sensitive data like API credentials, it's safer to use the current value of an environment variable for these. You will not be able to Persist the current values to update the initial values of environment variables without edit access to the environment. You can use the Reset option to update your local current values with the shared initial value at any time.

Requesting environment access

If you need to update the initial value of a variable in an environment you have readonly access to, you can request edit access. Open the environment from Environments on the left of Postman and click Request Access.

Viewer role on environment

Select the team member you want to submit the request to, and choose Editor from the drop-down list. Click Request Access. You will receive an email when your request is approved.

Using an environment in editor role

If you have edit access to an environment, you can update the variable values from the Postman UI and from your scripts. If you are using sensitive data such as personal or development / test credentials, make sure you only update these in the current value of a variable so that you do not accidentally share this information with your team.

When you edit the initial value of a shared environment variable, your updated value will be reflected for everyone who has access to the environment, so ensure that you only do this when you are happy for your value to be synced with the Postman servers.

If you uncheck (deselect) a variable in your environment, it will only be available to collaborators who also have edit access to the environment (and its enabled / disabled status will be reflected for them). Anyone with the viewer role for the environment will not see the unchecked variable. Disable environment variable

With editor role, you can configure access for other team members. If you need to specify access but do not have the editor role, you can request access.

Next steps

Shared environments allow you to leverage collaboration within Postman. Check out some more resources on how you can work with team members on your API development projects:

Last modified: 2022/01/12