Using the Postman Collection to call REST APIs over mTLS

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.

Additionally, because you are using an mTLS connection, your application must also present a Transport Certificate, which an Admin user can obtain from 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

  • OpenSSL installed on your machine

The set up for using mTLS with our Postman Collection differs slightly from the TLS setup. Before starting, ensure you have installed OpenSSL on your machine as this is required to generate a Transport certificate.

To set up Postman for mTLS, 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: Create Transport Certificate in Thredd Portal

To use mTLS for the Postman Collection you must first create a Transport Certificate, which is done in Thredd Portal.

To create a Transport Certificate in Thredd Portal:

  1. Open the System Admin menu and select Applications.

  2. Click Actions for the application you want to create a certificate for and click Review Application.

  3. Open the Certificates tab and click New Certificate. The New Certificate window opens.

  4. Select Transport in the Certificate Type field and click Next.

  5. Copy the generated CSR.

  6. Open a command prompt on your device.

  7. Paste the CSR into the command prompt. Two files are created - a CSR file and a KEY file.

  8. Return to Thredd Portal and click Next.

  9. Click on the window and navigate to and select the CSR file created in the previous step.

  10. Click Save. The window closes and the Certificates tab updates with the new Transport certificate.

  11. Click Actions on the certificate and click Download Certificate.

Step Three: Add Transport Certificate and Key to Postman

To add your certificate and key to Postman:

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

  2. Click Certificates.

  3. Click Add Certificate.

  4. Enter uat-api.thredd.com in the Host field.

  5. Click Select File under the CRT file heading. A window opens.

  6. Navigate to the where you saved your Transport certificate and select the PEM file. Click Open. The window closes and the certificate is added to Postman.

  7. Click Select File under the KEY file heading. A window opens.

  8. Navigate to the where you saved your Transport key and select the KEY file. Click Open. The window closes and the key is added to Postman.

  9. Click Add.

The Transport Certificate is now added to Postman.

If the certificate is not included in Postman, the API requests still work but they are downgraded to a TLS connection. You can confirm that your connection is mTLS by viewing the Postman console and ensuring there is a client_certificate section included. This indicates the request has used a mTLS connection.

Step Four: 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 Five: 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 Six: 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 Seven: 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 Eight: 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

Once 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.