The API Hub enables a single, global entry point into the Thredd platform. This includes:

• a unique URL
• a central authentication/authorisation component acting as a Policy Enforcement Point (PEP)
• central logging for all incoming requests

Here, you can learn about:

• Downloading the latest Postman Collections for TLS and mTLS
• Base URLs
• Generating an access token from the OAuth endpoint
• Configuring headers

Prerequisites

Before you can make API calls via API Hub, your organisation's Admin user must set up your applications and users in Thredd Portal to register them within Thredd's Secure Framework. This combines several components that enable secure access to Thredd's resources using a common identity store, over TLS (Transport Level Security) or mTLS (Mutual Transport Level Security). An Organisation Admin must set up their access and log in to Thredd Portal before configuring and testing access to Thredd's API Hub and REST APIs. If you are a non-Admin user who does not have access, contact your Admin to arrange this.

To connect to the API Hub, a Thredd Portal Admin user must do the following:

• Create an application and OAuth Client in Thredd Portal.
• Obtain the credentials that you need to connect to the API Hub, depending on your application's authentication method. For example, the Client ID and any certificates to generate authentication tokens. Client Secret requires an access token.

Best practice

• When implementing an API call, you must at a minimum include the mandatory request fields and handle the fields that are mandatory in the response.
• Where a field requires you to submit a code value or returns a code value, the API documentation provides links to the relevant appendix for details. If you are unsure about which code to include in your request, use the default or recommended value.
• Do not use spaces in field names.
• Test making calls in the UAT (User Acceptance Test) environment first. Using Thredd's Postman Collection is ideal for testing this. Once you are satisfied with testing in the UAT environment, your Admin user can prepare for migrating to a Production environment.

Download the Postman Collection

Download the latest Postman Collection using one of the following links and follow the set up steps in the Connecting to Thredd Guide that match your configuration:

• Postman Collection for TLS connections
• Postman Collection for mTLS connections

Authentication

Authentication to the API Hub is handled through Thredd's Secure Framework. Thredd supports the following Client Authentication methods for connecting to the REST APIs:

• Client Secret — requires an access token, which you can generate using your application's Client ID and Thredd's OAuth endpoint.
• Mutual TLS connections also require a Transport Certificate from Thredd, which you must include in all requests to the API Hub.

Thredd adopts a self-service approach, which allows Admin users to independently request and manage certificates, such as Transport certificates, in Thredd Portal. Your organisation's Admin user can provide you with the information you need to generate tokens and configure your REST tool or Thredd's latest Postman Collection to make API calls. For more information about how to complete these tasks, see Connecting to Thredd Guide.

Base URLs

There are different base URLs available for the API Hub, depending on the environment that you are using. The URL remains the same regardless of connectivity type being used.

See the following example of the Create Card endpoint in the Core API using the production base URL.

https://api.thredd.com/core/api/v1/cards

Accessing API Hub as a new client

The following section is a summary of the steps that you need to follow to access the API Hub as a new client. You must configure your REST tool with the appropriate settings. For a full guide to connecting to the REST APIs and configuring the Postman Collection, see Connecting to Thredd Guide.

1. Set the correct base URL for the environment and endpoint that you will use.
2. Add the x-region header — this is mandatory and determines the region/environment you are trying to connect to. Select from:
3. • Use 0 for the Default environment
   • Use 1 for the EMEA environment
   • Use 2 for the APAC environment
4. Set the content-type header — this is the media type of the requested resource. Example value: application/x-www-form-urlencoded
5. Request credentials to access the endpoints.
6. Include your OAuth token in the authorization header as appropriate for your application's authentication method. You can either use the endpoint within the Postman Collection or call the OAuth endpoint directly.

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.

Generating an Access Token

You must generate an access token to access the API Hub by making a POST request to the OAuth endpoint. This is mandatory for a Client Secret. You must include the access token in the Authorization header to ensure that your requests are successful. The access token is tied to the specific credentials that you pass in the request to the OAuth endpoint.

https://identity.cloud-uat.threddid.com/oauth2/token

Token expiration

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.

If a token has expired when your application makes a request against an endpoint, the API returns a 401 error. In this scenario, you must generate a new access token.

Client Secret authentication

You must provide your:

• Client ID
• Client secret
• If you use an mTLS connection, you must also include your Transport Certificate in your request to the OAuth token and other endpoints. The Authorisation Server will reject all requests without this.

See the following example OAuth token request body from the Postman Collection for a TLS connection (no Transport Certficate):

curl --location 'https://identity.cloud-uat.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'

Example OAuth token response

A successful request returns a 200 response and a valid access token.

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

Example request headers

See the following examples of headers for the Create Card endpoint. Note that the URL is different depending on whether you are using TLS or mTLS connectivity.

curl --request POST \
     --url https://api.thredd.com/core/api/v1/cards \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/*+json' \
     --header 'X-Region: 0' \
     --data '

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

curl --request POST \
     --url https://api.thredd.com/core/api/v1/cards \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGciOi...' \
     --header 'content-type: application/*+json' \
     --header 'X-Region: 0' \
     --data '...'

Accessing API Hub as an existing Cloudentity and Raidiam Connect user

Thredd is removing support for Cloudentity and Raidiam Connect (for mTLS connections) for handling authentication and issuing certificates. If you have previously used Cloudentity and Raidiam Connect, your organisation's Admin user must migrate your organisation's connectivity, access and certificate management to Thredd Portal and the Thredd Secure Framework.

Thredd will notify all clients this applies to and provide documentation to help clients migrate, and configure their environments, base URLs, and new Postman Collections. The new resources do not include references to Cloudentity or Raidiam Connect, and do not accept keys or certificates that have not been issued by Thredd.

Accessing API Hub as an existing Thredd Core API (V1.0) user

Clients who are currently using Thredd's legacy REST solution, Core API (V1.0), and have been instructed to change to API Hub (V2.0) by a Thredd representative must integrate with Thredd's Secure Framework.

You will need to change the base URL that you use to access the REST API endpoints. This is because the API Hub (V2.0) base URLs are different for those that you previously used in the legacy REST Cards API (V1.0). See Base URLs.

Contact your Account Manager to integrate to Thredd's Secure Framework.

Accessing API Hub as an existing SOAP user

If you are a client that is currently using our SOAP services, you need to update your integration to use REST. This can involve significant effort, but will reduce the integration work required as new services become available. The REST to SOAP conversion service provided by the API Hub ensures feature parity with the existing SOAP integration.

Since you are effectively changing your current integration, you can follow the same instructions as a new client. For more information, see Accessing API Hub as a New Client and the Connecting to Thredd Guide.