Creating a Setup Phase with Subtests: How to Handle OAuth 2 Access Tokens using the Runscope API

In a recent post, we announced a new feature called Subtest Step. Today, we’re going to be looking at one of the most common use cases for it: creating a “Setup” phase to always refresh your access token. With this, you can easily monitor and test any API that implements OAuth 2, without having to worry if your token is valid or not.

A few things before we start:

• This tutorial is going to focus on how to handle Access and Refresh Tokens inside of Runscope. You should be familiar with OAuth 2, as we won’t be going to deep into it.
• This should work for any API that implements OAuth 2.
• If you need to quickly go through an Authorization Code Grant Flow to get your first access/refresh tokens, check out our OAuth Token Generator tool.
• To use the Runscope API, we’re going to need a Runscope access token. The API uses OAuth 2.0, so you’ll need to create an application from your profile Applications page. That will provide you with a Personal Access Token which can be used as an OAuth bearer token to access data in your account. If you need help creating an application, please check our blog post “Quickstart Guide to the Runscope API.”
• Please be careful when making changes to a live environment. Make sure to thoroughly test the steps below in a separate environment or bucket before committing them to your production tests.

OAuth 2 Access and Refresh Tokens

So, let’s say you went through an API’s Authorization Code Grant Flow, and got your access and refresh tokens. You’re ready to start creating tests for your API and monitoring it. But, before each test, you want to create a setup phase to get a new access token. How can we do that?

Well, three easy steps:

1. Create a Shared Environment with your tokens
2. Create a new test that will: get new tokens, and update our Shared Environment using the Runscope API
3. Add our test from the previous step as a Subtest in any other test

Let’s dive right in!

Setting up a Shared Environment with an Access Token

The first thing we should do is create a Shared Environment for our tests and add two variables for our tokens so that they are easily accessible:

Also make sure to copy our newly created shared environment UUID, which we will use in the next steps:

Creating a New Test and Getting a New Access Token

Now, we want to make sure we always get a new Access Token before each test as our setup phase. Let’s create a new test to do that.

The following steps are just an example placeholder. Every API is different, so this is where you will update your request with the necessary information for your API: the request endpoint that will return a new access and refresh tokens, any authorization headers, and any variables you might need.

For this tutorial, the only thing we want to make sure to do this for this step is to extract our new access and refresh tokens from the API response. We’re storing them in the variables newAccessToken and newRefreshToken.

Updating your Shared Environments Variables with the Runscope API

Next, we are going to add two request steps to our test. Both requests are going to hit the same endpoint with two different HTTP methods:

https://api.runscope.com/buckets/<bucket_key>/environments/<environment_id>

The first thing we need to do is GET our shared environment settings and extract the JSON result.

You can see the endpoint includes a <bucket_key> and <environment_id> variables. We can replace the first with one of the built-in variables in the Test Editor: {{runscope_bucket}}. That will automatically replace it with your test’s bucket key.

The second one, <environment_id>, can be replaced by the UUID from the shared environment you created at the beginning of the tutorial. So you can directly paste that at the end of the URL, or store it in an initial variable and use that instead.

We also need to use our Runscope API personal access token to access this endpoint. So, if you’re familiar with OAuth 2, all you need to do is add an Authorization header to our request with the format “Bearer your_runscope_api_key_here”.

Getting the Shared Environment Settings

Remember to create a variable to extract and store the JSON result. That will include all the current settings for our shared environment.

Updating and Saving the Shared Environment Settings

For this next step, we’re going to start by duplicating our last request. Then, all we need to do is change our method to PUT instead of GET and add a small pre-request script to our test:

var envSettings = JSON.parse(variables.get("envSettings"));
envSettings.initial_variables.accessToken = variables.get("newAccessToken");
envSettings.initial_variables.refreshToken = variables.get("newRefreshToken");
request.body = JSON.stringify(envSettings);

The script will do a few things:

• Retrieve the variable envSettings from the last step, which includes the JSON result of our shared environment settings.
• Update our shared environment variables to include our new tokens.
• Set our new shared environment settings to the request body, so it gets saved when we make our PUT request.

Using the “Get Refresh Token” as a Subtest

Now to the fun part! We’re ready to make authenticated requests to our API, and we can create as many API tests as we want and just reuse our Authentication Test as a Subtest. :)

To do that, make sure to:

• Set your test’s environment to use or inherit the shared environment containing your access token variable.
• Add a subtest step to your test, and set it to our newly created test to refresh our access token.

And now you can use your access token variable anywhere throughout your tests, and not have to worry about expired tokens.

Bonus

Sam, our awesome Customer Success Engineer here at Runscope, created a template for the steps above. So, if you know what you’re doing and just want a head start, download this JSON and import it as “Runscope API Tests.” To give it a try, all you need to do is create a shared environment and add two initial variables to the imported test:

• runscope_token - Your Runscope API token.
• shared_environment - Your shared environment UUID.

Conclusion

This is just one of the use cases for Subtest Steps, and we hope you find it useful! In some cases, you might want to check if your access token is expired before getting a new one, or only get one after a set period of time. If that’s something you’d like to see us write about, or need help setting up, please let us know at help@runscope.com.

In our next post about Subtests, we’ll cover how you can use them to better organize your tests.

Everything is going to be 200 OK®

Originally published at blog.runscope.com.