Documentation
thredd.comDocumentation Portal
Start typing to search…

Accessing API Hub

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

Prerequisites

Before you can use the API Hub, you must be set up on Thredd's Secure Connectivity Framework. This is a combination of several components which enable secure access to Thredd’s resources, using a common identity store. The main components related to the API Hub are:

  • CloudEntity
  • Raidiam Connect

CloudEntity

A Software as a Service (SaaS) capability which acts as the Identity Provider (IDP) for Thredd’s interfaces (including Raidiam Connect and Thredd Portal) and as an OAuth OpenID Provider (OP) for the registration and management of customer applications, generation and validation of access tokens, and for the enforcement of access control policies.

Set Up CloudEntity

  • Thredd sets up CloudEntity for you to enable a Single Sign On journey by linking your IdP with CloudEntity. If you do not use an IdP, CloudEntity can act as the IdP.
  • A Single Sign On journey is used to access Raidiam Connect for the creation of certificates, as well when connecting to the Thredd Portal card management application. In both cases, there is at least one additional Admin user, who manages users. Once set up, your organisation is unlikely to need to engage with Thredd for integrating CloudEntity.
  • CloudEntity is also used behind-the-scenes for managing access to the REST API as an Authorisation Server.

Raidiam Connect

Raidiam Connect is Thredd’s Certificate Authority for setting up and managing certificates to connect to various services. The certificates include:

  • Transport Certificates — for establishing secure connections between resources.
  • Signing Certificates — for the creation of signed messages, used for authentication of clients, and non-repudiation and authentication of notifications.
  • Encryption Certificates — for the encryption of payloads using an asymmetric encryption approach.

Set Up Radium Connect

Thredd will provide access to Raidiam Connect. Thredd adopts a self-service approach, which allows you to independently manage your certificates.

To request access to Raidiam Connect, please raise a support ticket.

📘

Note

For more information on connecting to Thredd, see the Connecting to Thredd Guide.

Base URLs

There are two base URLs available for the API Hub, depending on the environment you're using.

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

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

Accessing API Hub as a New Client

The following section describes the steps you need to follow to access the API Hub as a new client.

Step One - Request an Access Token

Request an access token by making a call to the Get Access Token endpoint.

See the below example of a successful Get Access Token response. Access tokens are valid for 10 minutes and include the scopes that are associated with your application.

{
    "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjI4MjE0MTkzNzIxODQ1ODQ2MTM4MDA3OTA2MDQwMzExOTc1ODE0NCIsInR5cCI6IkpXVCJ9.eyJhaWQiOiJjb25maWRlbnRpYWwtY2xpZW50cyIsImFtciI6W10sImF1ZCI6WyJodHRwczovL3JwLmRpcmVjdG9yeS5zYW5kYm94LnRocmVkZGlkLmNvbS9vcGVuaWRfcmVseWluZ19wYXJ0eS8xMzNkMTI2OS01NWVlLTQyYjctYmE3My0wNjA4MzhjMDc0YWUiLCJzcGlmZmU6Ly91YXQtdGhyZWRkLmV1LmF1dGh6LmNsb3VkZW50aXR5LmlvL3VhdC10aHJlZGQvY29uZmlkZW50aWFsLWNsaWVudHMvY29uZmlkZW50aWFsLWNsaWVudHMtb2F1dGgyIl0sImNuZiI6eyJ4NXQjUzI1NiI6IkkzZ0QyZVFydlhlcTBsMWNyR2pqS1A1VjVWX0REc1U1MURXQjRPcFZ2M00ifSwiZXhwIjoxNzQzMDgyOTk4LCJpYXQiOjE3NDMwODIzOTgsImlkcCI6IiIsImlzcyI6Imh0dHBzOi8vdWF0LXRocmVkZC5ldS5hdXRoei5jbG91ZGVudGl0eS5pby91YXQtdGhyZWRkL2NvbmZpZGVudGlhbC1jbGllbnRzIiwianRpIjoiZWMzNTY5MGItMmNkZC00YzJlLTk0ZjItODA1NWE0NGMwZTVkIiwibmJmIjoxNzQzMDgyMzk4LCJwbWlkIjoxNiwic2NwIjpbIjNkcy5yZWFkIiwiYXBhdGEucmVhZCIsImFwYXRhLndyaXRlIiwiYnVsa2NhcmQucmVhZCIsImJ1bGtjYXJkLndyaXRlIiwiY2FyZHMucmVhZCIsImNhcmRzLndyaXRlIiwiY3Z2LnJlYWQiLCJjdnYud3JpdGUiLCJkaWdpdGFsY2hhbm5lbCIsInBpbi5yZWFkIiwicGluLndyaXRlIiwic2NhbWRldGVjdCIsIndzIl0sInN0IjoicHVibGljIiwic3ViIjoiaHR0cHM6Ly9ycC5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vb3BlbmlkX3JlbHlpbmdfcGFydHkvMTMzZDEyNjktNTVlZS00MmI3LWJhNzMtMDYwODM4YzA3NGFlIiwidGlkIjoidWF0LXRocmVkZCJ9.jdRwIDZzv5tXuR6mPpFJ0JbqiCUCZ-ToDrluW7AxjEwu78krMYEkDawjhmIfmv8gKTb2qERmMEXxZnOBYuAZ8w",
    "expires_in": 599,
    "scope": "3ds.read apata.read apata.write bulkcard.read bulkcard.write cards.read cards.write cvv.read cvv.write digitalchannel pin.read pin.write scamdetect ws",
    "token_type": "bearer"

📘

Information

For more information on the Access Token, see Generate Authentication Token.

Step Two - Include the Access Token in the Authorisation Header

When using the endpoints in the API Hub, you must include Access Token in the header.

Step Three - Add X-Region Header

The X-Region header is mandatory in a header and determines the region/environment you're trying to connect to. Select from:

  • Use 0 for the Default environment
  • Use 1 for the EMEA environment
  • Use 2 for the APAC environment

Note: If you're not sure of the environment you should use, speak to your Account Manager or Implementations.

Accessing API Hub as an Existing REST User

The following section details how to access the API Hub if you currently access Thredd's API using REST services.

Step One - Integrate to Thredd’s Secure Connectivity Framework

Thredd’s Secure Connectivity Framework is the combination of several components which enable secure access to Thredd’s resources, using a common identity store.

Contact your Account Manager to integrate to Thredd’s Secure Connectivity Framework.

📘

Documentation

For more information, see the Connecting to Thredd Guide.

Step Two - Change the Base URL to the API Hub

You need to change the base URL for the endpoints to access the REST API endpoints you used in REST Cards API. The base URL for API Hub is https://api.thredd.com/ for production, and https://uat-api.thredd.com/ for UAT. The below example shows the URL for the Create Card endpoint in the API Hub production environment.

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

Step Three - Request an Access Token

Request an access token by making a call to the Get Access Token endpoint.

See the below example of a successful Get Access Token response. Access tokens are valid for 10 minutes and include the scopes that are associated with your application.

{
    "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjI4MjE0MTkzNzIxODQ1ODQ2MTM4MDA3OTA2MDQwMzExOTc1ODE0NCIsInR5cCI6IkpXVCJ9.eyJhaWQiOiJjb25maWRlbnRpYWwtY2xpZW50cyIsImFtciI6W10sImF1ZCI6WyJodHRwczovL3JwLmRpcmVjdG9yeS5zYW5kYm94LnRocmVkZGlkLmNvbS9vcGVuaWRfcmVseWluZ19wYXJ0eS8xMzNkMTI2OS01NWVlLTQyYjctYmE3My0wNjA4MzhjMDc0YWUiLCJzcGlmZmU6Ly91YXQtdGhyZWRkLmV1LmF1dGh6LmNsb3VkZW50aXR5LmlvL3VhdC10aHJlZGQvY29uZmlkZW50aWFsLWNsaWVudHMvY29uZmlkZW50aWFsLWNsaWVudHMtb2F1dGgyIl0sImNuZiI6eyJ4NXQjUzI1NiI6IkkzZ0QyZVFydlhlcTBsMWNyR2pqS1A1VjVWX0REc1U1MURXQjRPcFZ2M00ifSwiZXhwIjoxNzQzMDgyOTk4LCJpYXQiOjE3NDMwODIzOTgsImlkcCI6IiIsImlzcyI6Imh0dHBzOi8vdWF0LXRocmVkZC5ldS5hdXRoei5jbG91ZGVudGl0eS5pby91YXQtdGhyZWRkL2NvbmZpZGVudGlhbC1jbGllbnRzIiwianRpIjoiZWMzNTY5MGItMmNkZC00YzJlLTk0ZjItODA1NWE0NGMwZTVkIiwibmJmIjoxNzQzMDgyMzk4LCJwbWlkIjoxNiwic2NwIjpbIjNkcy5yZWFkIiwiYXBhdGEucmVhZCIsImFwYXRhLndyaXRlIiwiYnVsa2NhcmQucmVhZCIsImJ1bGtjYXJkLndyaXRlIiwiY2FyZHMucmVhZCIsImNhcmRzLndyaXRlIiwiY3Z2LnJlYWQiLCJjdnYud3JpdGUiLCJkaWdpdGFsY2hhbm5lbCIsInBpbi5yZWFkIiwicGluLndyaXRlIiwic2NhbWRldGVjdCIsIndzIl0sInN0IjoicHVibGljIiwic3ViIjoiaHR0cHM6Ly9ycC5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vb3BlbmlkX3JlbHlpbmdfcGFydHkvMTMzZDEyNjktNTVlZS00MmI3LWJhNzMtMDYwODM4YzA3NGFlIiwidGlkIjoidWF0LXRocmVkZCJ9.jdRwIDZzv5tXuR6mPpFJ0JbqiCUCZ-ToDrluW7AxjEwu78krMYEkDawjhmIfmv8gKTb2qERmMEXxZnOBYuAZ8w",
    "expires_in": 599,
    "scope": "3ds.read apata.read apata.write bulkcard.read bulkcard.write cards.read cards.write cvv.read cvv.write digitalchannel pin.read pin.write scamdetect ws",
    "token_type": "bearer"

📘

Information

For more information on the Access Token, see Generate Authentication Token.

Step Four - Include the Access Token in the Authorisation Header

When using the endpoints in the API Hub, you must include Access Token in the header.

Step Five- Add X-Region Header

The X-Region header is mandatory in a header and determines the region/environment you're trying to connect to. Select from:

  • Use 0 for the Default environment
  • Use 1 for the EMEA environment
  • Use 2 for the APAC environment

Note: If you're not sure of the environment you should use, speak to your Account Manager or Implementations.

Accessing API Hub as an Existing SOAP User

If you are a client 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 all of you current integration, the same instructions as a new client can be followed. See Accessing API Hub as a New Client for more information.

Updated 16 days ago