Connecting to the REST APIs

There are two main areas in which you will need to set up your connection to access Thredd REST APIs:

Thredd Portal: Log in to Thredd Portal and obtain the credentials for your existing application and OAuth Client. This is the application that currently connects to Thredd REST APIs via the API Hub. If you need to create a new application and OAuth Client, you can do so here.
A REST tool: Configure your REST interface, such as Postman, to interact with the Thredd platform, so that you can access the API endpoints.

For best practice, Thredd recommends that an Organisation Admin first sets up your organisation's access in the UAT (User Acceptance Test) environment. This enables you to test and verify that your organisation can use the API endpoints successfully. Once an Admin has verified that your testing in the UAT environment is satisfactory, you can prepare for migrating to a Production environment.

For your Production environment, you will need to request new credentials and ensure that the environment-specific configuration is correct. Make sure that old credentials are not cached, such as a certificate or token, and that you send updated credentials to Thredd.

Overview of set up steps

You need to complete the following steps to migrate your connection to Thredd.

Get credentials for your client application via Thredd Portal.
Configure your REST tool to interact with Thredd to make calls to Thredd API that include an access token. You must obtain an access token using your client credentials. You can also download Thredd's Postman Collection and configure your client credentials as variables in Postman to test making API calls in a UAT environment.
Get an access token from Thredd's OAuth token endpoint to include in the Authorization header of your API request.
Make a call to Thredd's REST API to test your setup.

Step 1: Get credentials for your Application via Thredd Portal

To access any Thredd API endpoint you must exchange your client credentials for a short-lived Bearer token (OAuth token).

When you have obtained your credentials, you must request an OAuth token and include it in the header of your requests to the REST API endpoints. To get an OAuth token, you can either use the endpoint within the Postman Collection (when testing in a UAT environment) or call the OAuth Token endpoint directly when using a Production environment (see step 3).

Complete the following steps to obtain the information you need via Thredd Portal, based on your Client Authentication method.

You must have created an application and OAuth client in Thredd Portal. If you have not already done this, see Creating an Application and OAuth Client.

Client Secret authentication

You need:

Client ID of your application
Access token from Thredd's OAuth Token endpoint
If you use mTLS, you also require a Transport Certificate from Thredd

Get the Client ID:

In Thredd Portal, navigate to System Admin, and select Applications. Select the Actions menu (icon of three dots) and select Review Application. A screen appears with tabs for the OAuth Clients and Certificates for your Application.
On the OAuth Clients tab, locate the OAuth Client that you will use to connect to the Thredd REST APIs. Select the Actions menu (icon of three dots) and select View Details. The Overview screen for the OAuth Client appears.
On the Overview tab, locate the Client ID and Client Secret under Client Configuration. You can copy these values from here when you need to.

Get a Transport Certificate — for mTLS connections:

If you are using an mTLS connection, your application requires a Transport Certificate for establishing mutual connections between your Client and Thredd. An Admin user can obtain a Transport Certificate from Thredd Portal. See Requesting certificates for applications using mTLS.

Step 2: Configure your REST tool to make calls to Thredd API using your client credentials

You can access Thredd's API Hub and REST APIs over mTLS. You must make sure that you configure your REST tool with the appropriate settings, for example:

Base URL — this depends on whether you are using the UAT or Production environment.
Headers — you must set the correct Authorization, Content-Type, and X-Region headers.

Base URL

Connectivity for the UAT environment: uat-api.thredd.com
Connectivity for the Production environment: api.thredd.com

Configuring headers

Whether you are using your own tool or the Postman Collection, you must make sure that you configure the following headers with the correct information in each API request. These headers are mandatory for all to the API Hub.

Authorization header — include your OAuth token in the authorization header as appropriate for your application's authentication method.
X-Region header — this is mandatory and determines the environment you are trying to connect to. Specify one of the following values in the X-Region header:
- 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
If you are not sure which environment to use, contact your Thredd Account Manager or Implementation team. By default, the Postman Collection is set to use the Production 0 environment (Prd0), but you can change this in the variables section.
Content-Type header — specify the media type of the requested resource in the content-type header. Example value: application/x-www-form-urlencoded

For some endpoints, you can pass pagination values. Where this is relevant, this is stated in the documentation for a given endpoint in API Reference on the API Hub.

Thredd provides Postman Collections that enable you to use Postman to test using the Thredd REST APIs in a UAT environment. To use the collection, you need to configure Postman with the appropriate environment variables and credentials.

If your integration currently uses an environment-specific API URL, such as https://coreapi-prdX.threddpay.net, update it to use the current production API Hub endpoint: https://api.thredd.com/core/, and ensure the X-Region header is set to the correct value for your required environment. For UAT, use https://uat-api.thredd.com/core/ instead.

Postman Collection

Download the Postman Collection from the API Hub and follow the guide:

For mTLS connections: Using the Postman Collection to call REST APIs over mTLS
To download the Postman Collection, see Accessing the API Hub.

Step 3: Get an access token using your client credentials

You must request an access token from Thredd and include it in the Authorization header of your requests to the REST API endpoints. You can get an access token using the following methods:

Use the endpoint within the Postman Collection (when testing in a UAT environment).
Call the OAuth Token endpoint directly when using a Production environment.

Access tokens are valid for fifteen minutes and include the scopes that are associated with your application.

Follow the advice that match your Client Authentication method.

Client Secret authentication

You must provide your:

Client ID
Client secret

Endpoint:

POST https://threddid.com/oauth2/token

Example request body (URL-encoded):

Copy

curl --location 'https://threddid.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=YOUR_CLIENT_ID'
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET'

If you use an mTLS connection, you must also include your Transport Certificate in your request to the OAuth token endpoint. The Authorisation Server will reject all requests without this.

Example OAuth token response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}
                                            

Access tokens are valid for one hour and include the scopes that are associated with your application.

You must configure your application to refresh the token automatically when it expires.

Step 4: Make a call to Thredd's REST APIs

Once you have the access_token, you must include it in the Authorization header of every request to Thredd's REST APIs.

The next step is to test making an API call. Refer to the documentation for the base URLs and API Reference for endpoints at the API Hub: https://cardsapidocs.thredd.com/v2.0/docs

Remember to include the following in your requests:

Base URL — this depends on whether you are using the UAT or Production environment.
Mandatory information in your request headers.
Correct HTTP method for the endpoint.

If you change the environment or region that you want to make API calls to, you must update the Base URL and headers that you include in your requests.

Example request header (mTLS)

Copy

GET /core/api/v1/products HTTP/1.1
Host: api.thredd.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

For mTLS, when making your request to uat-api.thredd.com (UAT environment) or api.thredd.com (production environment) you must also include your Transport Certificate in the request. Thredd's APIs will reject all requests that do not include this.