Using Postman Environment Variables & Auth Tokens

http://getpostman.com

An ever increasing part of our job as developers these days is creating back-end apis. There are a lot of great tools being developed to help with building and testing these, but Postman is one of Mahana Designs’ most critical. Postman lets you create the urls you need to imitate an iOS app or Curl making calls to your api.

(This article is completely language and framework generic, but its original form appeared as one of my Laravel Quick Tips newsletters. Do join us if Laravel and related topics interests you!)

Two tricks I want to show you today that are *enormous* time-savers. The first is using environments. In your Postman app, go to the little cog in the upper-right corner of the tool and you’ll see “Manage Environments”:

The Manage Environments menu

An environment in simple terms is just a set of variables which you will typically use for a specific website. You can have a different group of these for each site you are developing, and switch between them with the dropdown in this same area.

Add a new environment with your site’s local url and a blank token variable we’ll use in the second part of this article:

Adding variables to your environment

Now in the dropdown, select “MySite” (or whatever you named it). This will make the variable group we just created accessible when we are calling our endpoints. Open a tab and create a new url with a variable:

Calling the variable

When you “send” the url, the {{url}} will be filled in with your variable (you won’t see this replaced in your tab — it is done internally at runtime). Why is this cool? You can export your Postman collection and share it with everyone else on the team, and they can simply change that variable to their own local url or staging url without having to change every single endpoint! No more arguing over whether to use “.dev” or “.local” or whatever — everyone is free to do as they prefer. When it comes time to access staging and production machines, it is just another quick environment setup.

The second part of this is even better! These days using JWT Tokens and stateless APIs is the norm, which means you have to get a token and then pass it back with every request in the headers. That’s a pain! However, we can take advantage of Postman’s test scripting to handle this for us.

(Note: this is a fairly standard response setup, but you may need to tweak it to match your own.)

First, we have a POST endpoint to {{url}}/login that returns the token:

Sample token response from a login call

Assuming a response of {…, message.token} go to the “tests” tab and add this script:

Passing the response value to a variable dynamically

EDIT: In more recent Postman versions (not sure of the exact update) the code should be changed to:
var data = pm.response.json();
pm.environment.set(“token”, data.message.token);

Thank you to commenters who brought that to my attention!

This is just javascript, and should be pretty clear what is happening. That {{token}} variable we created is being populated with the setEnvironmentVariable() function. Now, go to any of your endpoints and set up your Headers:

The Bearer token setup

Now when you start your work session, just log in and all of your endpoints will have the token populated for you at once. That’s a bit of a time saver, I think. (Note — this is actually different than what we did before with {{url}}. If you look in your Manage Environments you’ll see token value has actually been populated. Very useful to know for debugging.)

Hope that helps!

Thanks for reading! If you found this useful, help me spread the word by passing it on. — Jeff