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 create a client application, and obtain the client credentials for your application.
A REST tool: Configure your REST interface, such as Postman, to interact with Thredd's identity and access management platform, so that you can access the API endpoints.

For best practice, Thredd recommends that the 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 set up your connection to Thredd for the first time.

Create a client application and OAuth Client in Thredd Portal and get a Client ID. If you have already done this, see step 2.
Get credentials for your client application via Thredd Portal.
Configure your REST tool to interact with Thredd to make calls to Thredd's 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: Create a Client Application in Thredd Portal and get a Client ID

In order to call Thredd's REST APIs, you need to create an application and OAuth Client in Thredd Portal. This registers your client application with the Thredd's identity and access management platform. Make a note of the Client ID of your application.

See Creating an Application and OAuth Client.

Step 2: 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).

You must make sure that you provide the Client Secret from Thredd to obtain an access (OAuth) token for Thredd's REST APIs.

When you have obtained your Client Secret, 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.

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 and Client Secret:

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 the values from here when you need to.

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 a Transport Certificate for applications using mTLS.

Step 3: 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 TLS or 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

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 requests that you make 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. Select one of the following values to include 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 Prd 0 (Production 0) environment, 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 separate Postman Collections for TLS and mTLS, which 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.

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.

Postman Collection

Download the Postman Collection from the API Hub and follow the guide that matches your configuration:

For TLS connections: Using the Postman Collection to call REST APIs over TLS
For mTLS connections: Using the Postman Collection to call REST APIs over mTLS

To download the Postman Collection, see Accessing the API Hub.

Step 4: 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 15 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 15 minutes and include the scopes that are associated with your application.

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

Step 5: 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 (TLS)

Copy

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

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.