Box Postman advanced collection

Image By freepik

In this article we'll explore how we've converted the pre-request script to handle any type of Box application authentication, giving developers greater flexibility in using the API collection in their development process.

Our classic Postman collection constitutes a fundamental interface for developers to interact with the Box Platform API.

Between endpoints and methods we count around 150 items, so this is a fairly large collection, organized by areas.

The issue with the classic collection is that only support OAuth 2.0 authentication, refreshing the access token after it expired. The application authorization process was automated by using the Postman quick start in our guide, although Postman it self supports this.

How to work with the Advanced Collection

Based on the Postman environments, the pre-request script is able to identify the environment type, and then check if the access token has expired, fetching a new token as necessary.

This means a developer can have as many environments as needed, pointing to different Box applications, and quickly switch between them.

This comes in handy for example when you're developing an application using a service account, authenticated with Client Credential Grants (CCG), and you want to check if that service account does have access to specific content.

Another example would be to test what a downscoped access token has access to.

This way the developer is not limited by the OAuth authentication which is always using the security context of a specific managed user.

Here are some environment examples:

CCG environment

JWT environment

OAuth environment

Using the environments

Once the environments are configured, the developer can quickly switch between them and have a completely different security context for the request.

The pre-request script will identify the environment type, check if the access token has expired, fetch a new one if needed, and execute the request.

Executing a request with a JWT environment and an expired access token

How to set up the Advanced Collection

Each environment type is different and has a lot of parameters such as client_id and client_secret . In order to try to make the environment creation easier, we threw in a few methods under the utilities folder, using the Postman API and features to automate this area.

However there are no free lunches, so the developer has to set this up once.

Here are the steps.

Get a Postman API key

In order to use the Postman API you'll need an API Key. Navigate to your account and create one.

Creating a Postman API Key

Then navigate to the Create Environments folder and under the Authorization tab set a global variable with the key you've just created.

Setting a global variable with the created key

From here you'll be able to make requests using the Postman API.

Configure the workspace

Environments are created in workspaces. For this you'll need to identify your workspaceid . We've added the get workspaces method for convenience. You should be able to list your workspaces from here and copy the correct id.

Listing my environments

Each create environment method accepts a {{workspaceid}} variable. Go ahead, create a global variable and set it with the workspaceid from the previous request.

Setting the workspaceid variable

Creating an environment

Remember you'll need to do the above steps only once.

Finally you can create environments. We found out that the easiest way is to just give the environment name, create an empty environment, and then fill in the variables manually. See what works best for you.

Each environment type has plenty of parameters to be filled in the request body. At a minimum set the environment name:

Creating a CCG environment

Once you execute the request, you can fill in the variables from your Box app configuration.

Configuring the environment.

Remember to save!!!

To test if it works, select the new environment, select the Test Environment method and click send.

Testing the environment

Other types of apps/authentications/environments, can be configured the same way.

If you wan to use a JSON Web Tokens (JWT) authentication, you most likely have a config file generated from your app:

JWT app configuration

The config file looks something like this:

{
  "boxAppSettings": {
    "clientID": "febb9yq9nidfszj63ylzshqf2cg4emso",
    "clientSecret": "3N...Exi",
    "appAuth": {
      "publicKeyID": "39749s1s",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...MIIlCE=\n-----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "fa...c3"
    }
  },
  "enterpriseID": "877840855"
}

Just copy and paste each one to the environment configurations.

The OAuth 2.0 special case

OAuth 2.0 has both an access token and a refresh token.

At Box access tokens last for 60 minutes and the OAuth refresh token for about 60 days. When an access token expires, it can be refreshed using the refresh token, and you'll get brand new tokens for both access and refresh with 60 minutes and 60 days respectively.

This means you can refresh an expired access token within the 60 days, and get both new tokens, where the refresh token is valid for the next 60 days. If the refresh token expires, the user must re-authorize the app.

OAuth 2.0 design implies a user has to explicitly authorize an application to to access resources on their behalf. This triggers a 2-step process where the user is re-directed to the authentication page, authorizes the app, and then is redirected back. Of course Postman supports this.

As a pre-requisite your Box OAuth app must be configure to accept the Postman redirect URL https://oauth.pstmn.io/v1/callback

Configuring Box app to accept the Postman redirect URI

Next select an OAuth environment with at least the client_id and the client_secret configured.

Next, navigate the Authorize OAuth Box App folder, and flip to the Authorization tab, scroll all the way down and click the Get New Access Token Button. This will trigger the OAuth 2.0 process.

Starting the authorization process

Granting access to the app (notice the redirect)

The obtained token back in postman

Now you just need to fill in the environment variables with the information obtained.

However you do not have the refresh_token_expires_at , but you can use the timestamp adding an extra zero, as long as you don't forget to make a test call, that will retrieve fresh new tokens with the correct expiration.

I also found it helpful to copy this information to a text document first.

You might be asking by now, where can I get it?

You can fork this collection from the public Box workspace or directly using this link.

The Japanese collection can be forked from this link.

Thoughts? Comments? Feedback?

Drop us a line on our community forum.