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.
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.
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).
To create a new environment, select Environments on the left and click the + plus button.
Enter a name for your environment, and initialize it with any variables you need—you can alternatively specify variables for the environment later.
Click Save to save any environment variables you have added.
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 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.
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 clicking ... 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 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.
To use the variables in an environment, select it from the drop-down list at the top right of Postman.
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.
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.
You can access current environment variable values in your Pre-request and Tests code.
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 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.
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 editor role on the environment.
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.
You can also update environment variable values from your test 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:
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.
You can use environments to collaborate on your API development and testing processes with team members who share your workspace, environment, or collection. 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.
When you collaborate with your team 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.
By specifying role-based access to your environments, you can achieve a finer grained control level over your variable values. You can choose to share an environment within your workspace to make it available to team members—and specify access levels for each individual.
To share an environment to your workspace, open it from Environments on the left of Postman and click Share.
Select the workspace you want to share the environment to and choose whether to remove the environment from the current workspace when sharing. Click Share and Continue.
You can assign the same role to everyone in the workspace, or can configure access levels on an individual basis.
You can access the role control at any time from an environment by choosing Manage roles from the ... overflow menu.
Select roles, check the remove option if you wish to remove the environment from any workspace it is already shared in, and click Save Roles.
You can also remove a shared environment from a workspace by clicking ... next to the environment name and choosing Remove from workspace.
To export an Environment, click ... next to the Share button in the Environment overview. Select Export and confirm that you would like to export the environment from the current workspace.
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.
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.
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.
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.
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.
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.
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: