Using the Postman Collection to call REST APIs over TLS

Follow these steps to configure Postman with your client credentials so that you can obtain an access token. You must include an access token in all requests to Thredd's REST APIs.

You must make sure that you request and provide the Client Secret from Thredd to access Thredd's REST APIs. The Client Secret is selected as the Client Authentication method when setting up your organisation in Thredd Portal.

Prerequisites

You must have the following before setting up the IAM Postman Collection:

  • Administrator access to Thredd Portal

  • Postman

  • The Thredd IAM Postman Collection downloaded from here

  • The Thredd IAM Postman Environment file from here

To set up Postman for TLS, see the following steps.

Step One: Create Application and Auth Client in Thredd Portal

You can create an application and auth client in Thredd Portal. Successfully creating these produces a Client Secret and Client ID that you can enter into the Postman Collection.

Details on how to create an Application and associated Auth Client can be found in the Applications page of the Thredd Portal guide.

Step Two: Import Postman Collection into Postman

You can download the Postman Collection from the API Explorer page. Ensure you download the Thredd IAM API Collection.

When you have successfully downloaded the collection, open Postman and import the collection.

  1. Click File from the menu, then select Import.

  2. Drag the downloaded collection into the window.

The collection displays and opens in Postman.

Step Three: Import Postman Environment File

The Postman Environment file includes the variables for the Postman Collection to work, and is where you enter your Client Secret and Client ID into the collection. You can download the Postman Environment from the API Explorer page.

To import the environment file:

  1. Click File from the menu, then select Import.

  2. Drag the downloaded file into the window.

The environment variables are added to Postman.

Step Four: Enter Client Secret and Client ID into Postman

Before starting this step, ensure you have your applications Client Secret and Client ID ready.

To add the Client Secret and Client ID to the Collection:

  1. Use the dropdown in the top-right of Postman to select the UAT Thredd environment.

  2. Click the Variables button in the top-right corner of Postman. All variables for the environment display.

  3. Enter your Client Secret from Thredd Portal into the client_secret field.

  4. Enter your Client ID from Thredd Portal into the client_id field.

Step Five: Generate Authentication Token

Before you can use the API endpoints, you must create an authentication token. To create the token:

  1. Open the Authorisation folder in the Collection and select the Get Access Token endpoint.

  2. Click Send.

An authentication token is created and automatically added to your variables. This token lasts for 60 minutes. When the token expires you will need to generate a new token to continue using the APIs.

Step Six: Check your settings and finish setting up

Make sure that you have configured the following settings for your API calls:

  • You have set the correct Base URLs for the API Hub.

  • You have obtained an access token.

  • Including the access token in the authorisation header.

  • Adding an X-Region header — this is mandatory and determines the environment that you want to connect to; select one of the following options:

    • Use 0 for the Prd 0 (Production 0) environment

    • Use 1 for the Prd 1 (Production 1) environment

    • Use 2 for the Prd 2 (Production 2) environment

When you have completed these steps, you are ready to make your first API call. For more information, see the Thredd API Hub.

Thredd previously used environment-specific production core API URLs, such as https://coreapi-prdX.threddpay.net. Thredd now uses a single production core API Hub endpoint: https://api.thredd.com/core/, with the X-Region header used to specify the target environment. Ensure you use the correct production core API Hub URL and X-Region value for your environment. For UAT, use https://uat-api.thredd.com/core/ instead.

Preparing your Production environment

Once an Admin has verified that your testing in the UAT environment is satisfactory, you can prepare for migrating to a Production environment. You will need to repeat all of these steps for Production, such as requesting new certificates or access tokens, and ensuring that environment-specification configurations are correct. See Updating Postman.