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're 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.

Contents

Creating environments

You will see the selected environment status at the top-right of the Postman app. Any active environment will be selected in the drop-down, and to the right you will see the Environment quick look (eye) and Manage environments (gear) buttons.

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, click Manage environments at the top right of the Postman app.

Manage environments

You will see the list of existing environments in your workspace.

Manage Environments

Click Add.

Alternatively, select No Environment from the drop-down, open the Environment quick look, and click Add.

No Active Environment

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 Add to create your environment.

Adding environment variables

You can add variables to an active (currently selected) environment by opening the environment quick look using the eye button at the top right of the Postman app, and clicking Edit.

Edit environment

Alternatively, click Manage Environments and select the environment.

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 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.

Persist or Reset Environment

Accessing environments

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

To see all of your environments, click Manage Environments (gear button) at the top right of Postman.

Manage Environments

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

You can also view your environments in Browse mode—in Environments or Activity, click an environment name to see the variables within it in the web dashboard.

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:

{{base_url}}

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.

pm.environment.get("variable_key");

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

Editing environment variables

You can edit variables 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 Values will be synced with your Postman account and shared with any collaborators who have access to the environment. Click Update 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 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.

Edit environment variable

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 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, click Manage Environments (gear button) at the top right of Postman. Click Share next to the environment.

Share environment

Select the workspace you want to share the environment to. Click Share and Continue.

Share environment detail

You can assign the same role to everyone in the workspace, or can configure access levels on an individual basis.

Shared environment roles

You can access the role control at any time from Manage environments > 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 share environments from Browse mode in the Postman app by selecting Environments and clicking Share, then choosing a workspace. Alternatively, navigate to the environment from the dashboard via your team, workspace, activity feed, or the user profile of a collaborator by clicking Environments. Click Share next to the environment and choose a workspace to share it to.

You can also remove a shared environment from a workspace in Manage Environments by clicking ... next to the environment name and choosing Remove from workspace.

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're 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 the quick look (eye button) for an environment you will see an indicator if you only have view access, and the Edit button will be disabled—however, you can edit the current value inline.

Readonly environment

Viewer 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. Click Manage Environments (gear button) at the top right of Postman and click the environment name to open it. Click Request Access.

Request access on environment

Alternatively, in the environment list, click ... and choose Manage Roles > Request Access.

Request environment access

In the Dashboard, select the team member you want to submit the request to, and choose Editor from the drop-down list. Click Request Access.

Request environment access from team member

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 app 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: