Prior knowledge of basic OAuth flow is required for understnding this tutorial.
Postman is an amazing tool for working with REST APIs, from sending simple requests to using it as a full blown API test suite, it can do a lot of things. But only thing I find cumbersome is when working with OAuth in Postman. Don’t get me wrong, Postman has built in support for OAuth 2.0 authentication. My issues were with OAuth flows using the Refresh Tokens grant type.
Refresh Tokens are what you use to generate a new Access Token, whenever the current Access Token expires. Access Tokens may have a limited lifetime, say for example 10 minutes.
If you are doing this manually in Postman, you may have saved a Request for getting the Access Token, called it whenever the current Access Token expires and copied the newly generated Token and paste it in the Authorization header or in a variable. Although there is no out of the box way to achieve this in Postman, there is a fairly easy way to achieve this using Postman pre-request scripts (Postman Scripts Documentation).
Step 1: Setting up
Create a collection or folder to organize all the REST APIs that you want to use. This will help us create a common authentication mechanism for all the requests inside the collecton/folder
Setup the following environment variables:
- refresh_token: The Refresh Token that you generated using the OAuth flow (after user login prompt). The Refresh Token does not change. It can be passed to the auth server to get new Access Tokens.
- client_id: Your client id
- client_secret: Your client secret
- auth_url: The full OAuth token URL (eg: mywebsite.com/oauth/token)
Open the Edit window for your collection/folder (right click →edit). Open Authorization tab and select the type as ‘Bearer Token’. For the Token enter the value as:
The moustache syntax (double curly braces) refers to the value of a variable. You will get an error that the variable access_token is not declared, but you can ignore it. We will be setting the value of the variable though script in the next step.
Save the changes. Make sure that for any Request you create, the Authroization type is set to ‘Inherit from parent’ to use the configuration we made for the whole collection.
Step 2: Writing the script
- The pm.variables can be used to access and set the variables. It will first look for a variable in the Request, if not then in the Folder, then in Collection and finally in the Environment. Remember, we have declared some variables in the Environment in step 1.
- The pm.collectionVariables refers to the variables common to the whole collection. Since the same Access Token can be reused across different APIs, we will be storing the Access Token in the collection scope.
Postman also exposes a convenient sendRequest method for sending a request from within the code.
Now, if you run any Request inside the collection, first the script will be executed and an Access Token will be set in the variable. Then this variable will be used in the
Authroization: Bearer <access_token>
header for the request.
Step 3: Optimization
Requesting a new access token every time we send any request is an overhead. The Access Token expires only after said amount of time. Therefore we can store the time when we fetched the Access Token in a variable, and whenever a new Request is sent, we can check if the Access Token has expired or not.
This setup has saved a lot of time for me, and hope it does for you too. Cheers!