Good Practice: Using the gridX API with Postman

[a.roullet]

In this tutorial, you will learn how to quickly set up a Postman collection to start working with the gridX API!
We will go through how to make your first request using your bearer token and then how to use it to create a personal token for further requests.

Prerequisites

To follow this guide, you will need

• a working Postman installation (follow this link) and a Postman account
• a Xenon account

Steps

1. Download our API specs.
   

   

2. Head over to Postman, click on the Collections tab and select Import with the OpenAPI file you just downloaded.
   A new collection entitled Solution API should now be available.
   

   

3. Retrieve your bearer token from Xenon in the user settings.
   

   

4. Create a new Postman environment and store your bearer token in a secret variable called bearerToken as shown below.
   

   

5. Click on the Solution API collection and select the Authorization tab.
   We now need to set up the authorization header to use our bearer token for all endpoints of the collection.
   Choose the auth type Bearer with the variable bearerToken created in the previous step.
   

   

You now have everything set up to start calling the gridX API!
However, one downside of using bearer tokens is that they are short-lived, so you would have to overwrite your bearerToken variable every time it expires.

To provide a better experience, let’s create a personal token with a longer expiry date.

1. Navigate the collection through the collection and click on the endpoint “Create a Token” as shown below. In the Authorization tab, make sure the auth is inherited from the collection.
   

   

2. Make sure you have selected your Postman environment and call the endpoint with an expiry date in the future (e.g. in 6 months). You should get back a personal token in the response.

   Warning: This token must be stored securely like any password.

   

3. Head back over to the environment page and create a new token secret to store your personal token.
   

   

4. Personal tokens are used a bit differently from bearer tokens. They should also be part of the authorization header but they require the prefix Token. Navigate to the collection’s authorization tab and change the auth type to API Key with the prefix Token followed by your token. Make sure it is added to the header of the request and save the changes.
   

   

5. You can now call any endpoint with your personal token! For example, let’s retrieve the authenticated user.
   Don’t forget to check that the authorization is inherited from the parent.