Sessions FAQ

What are sessions?

Sessions provide an additional layer to hold collection, global, or environment variable values, that is unique to every Postman user and stays local to that user’s instance of Postman. Sessions contain variable values used to access and work with an API that a user may not want to share. Some examples of these values are login names, access tokens, passwords, and other private credentials.

The concept of sessions introduces a new scope which allows users to work with certain variables that remain local to their individual session, unless the user explicitly decides to sync their information to the cloud.

Why do we need sessions?

Sessions are particularly useful in Postman team workspaces where individual team members want to work with their own local copy of variables without affecting others. Sessions enable users working on a shared collection within a team to make requests using their own variable values without overwriting the original environment value.

How did these use cases work before Postman sessions?

While working out of a shared collection in a Postman Team, if any member of that team updated a global, collection, or environment variable’s value, that change would sync in real time and overwrite the initial value for everyone on the team. For example, if someone was testing a collection in a team workspace and they needed to modify an API key variable value, they had to duplicate the entire environment, share it to a personal workspace, and use it as a local environment — all to avoid overwriting the API key value contained in the original collection. This led to quite a few requests from our users for the ability to work with variables locally in Postman.

Now, with the addition of sessions, any team member can update a session value (referred to as CURRENT VALUES in the Postman app) within a shared collection without their change automatically syncing to the cloud, and thus updating the variable value for everyone else on the team.

What are best practices for using sessions?

While creating environment, global, or collection variables within a team workspace, it’s best practice to insert placeholder text like your-access-token-here or your-email-address if you intend for it to be overridden by other members of your team. This way, each team member can enter their own credentials as the CURRENT VALUE of the variable.

If you’re using these variables within a personal workspace, you can still rely on sessions to ensure your variable values are used locally and then decide when, and if, you want to overwrite your INITIAL VALUES.

How do I create sessions?

• Click on the Quick look icon (the eye) in the upper right corner of the Postman app
• Select either “Add” to add a new environment or “Edit” to add a global variable
• Set the variable name under the VARIABLE field
• Set the variable’s initial value under INITIAL VALUE (this value will sync across your team workspace)
• Set the session value under CURRENT VALUE (this value will remain local to your instance of Postman unless you take an additional step to persist your changes — more on this below)

Is there a way to edit sessions in line?

Yes! Once you’ve created sessions, you can quickly edit them in line if you:

• Click on the Quick look icon (the eye)
• Hover over the value you want to change under CURRENT VALUE until you see the pencil icon appear
• Click the pencil icon
• Update the CURRENT VALUE

What’s an example of how sessions can be used in Postman?

Let’s say Chakrit and Chris are part of a Postman Team. Chakrit creates a collection in their team workspace that requires each member of the team to enter their own email and password. Chakrit should set the initial value for those fields as something informative — but generic, such as your-email and your-password, and then share the collection with Chris, with edit access. Chris (and any additional team members) can then enter their own email and password under CURRENT VALUES to access the API, without overwriting the initial values, your-email and your-password.

Below you can see Chakrit’s response in the dark theme and Chris’s response in the light theme after updating their CURRENT VALUES.

How do I reset my local changes back to their initial values?

While adding or editing a variable, if you select “Reset all”, this will replace all CURRENT VALUES with INITIAL VALUES in your instance of Postman.

How do I persist session variables across my workspace?

While adding or editing a variable, if you select “Persist all”, this will replace all INITIAL VALUES with CURRENT VALUES across the entire workspace for that environment.