Creating an Application and OAuth Client

Before you can access Thredd's REST API, you must create an application and an OAuth Client in Thredd Portal to register it and receive a Client ID and Client Secret. You can then request client credentials for your application, and configure it and a REST interface (such as Postman) to provide credentials when making API calls. Think of the Client ID as the passport for your OAuth Client, and therefore your application. Combined with the credentials you need for your chosen Client Authentication method, it allows Thredd to verify your identity and grant access.

Summary of the steps

The steps for creating a new application and OAuth Client are as follows:

  1. Log in to Thredd Portal.
  2. Navigate to the System Admin menu, then select Applications.
  3. Create a new client application, adding a name and description.
  4. Create a new OAuth Client for the application.

  5. Optional, if you have more than one PMID, select the required PMID. Users with only one PMID will have it auto-selected.

Prerequisites

  1. You must have access to Thredd Portal.

  2. You must be an Organisation Admin for your organisation.

  3. You must have installed OpenSSL on the machine (the Server) that will make requests to Thredd platform (the Client).

Step 1: Log in to Thredd Portal

Log in to Thredd Portal and select System Admin. In System Admin menu, select Organisation, then Applications.

Step 2: Create a new client application

The Applications screen lists any applications that are registered in Thredd Portal.

If an existing application is already present (and you do not need to create a new one), then check whether an OAuth Client already exists for it. Select the Actions menu and select Review Application. Check the OAuth Clients screen; if an OAuth Client is not present, see step 3.

To create a new application:

  1. Select Add Application.

  2. The Create New Application screen appears. Enter the basic information, such as a name and description, for the application.

    Thredd recommends that you use an application name that you can easily identify for any application management activities. For example, to distinguish it from other applications when you need to obtain credentials, such as a Client ID, access token or certificate.

  3. Select Next and review the new application summary; select Back to make changes or select Create Application to save it.

  4. Your new application now appears in the Applications screen. Select the menu (three dots) under Actions and select Review Application.

Step 3: Create a new OAuth Client

The application details has one tab; OAuth Clients. MTLS users will have an additional Certificates tab. The steps to create an OAuth Client are as follows:

  1. In the OAuth Clients tab, select Create Client.
  2. The Create OAuth Client screen appears, starting with the Basic information stage. Enter the basic information, such as the Client Name and Description.

  3. Select the specific scopes from the ones available from the Allowed Scopes field. If none selected, all available scopes for the organisation will be granted.

  4. Click Next.

  5. Review the details of the client and the scopes associated with it. Scopes dictate what APIs you have permissions to use when calling the endpoints.

  6. Click Submit.

You have now registered a new OAuth Client, with a unique Client ID for your application. You can view it in the OAuth Clients screen of your application's details in Thredd Portal.

Next steps

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.

If you are using an mTLS connection, your application must also present a Transport Certificate from Thredd. Thredd adopts a self-service approach, which allows an Admin user to independently request and manage certificates via Thredd Portal.

See Connecting to the REST APIs.