Basic API Authentication

TxB APIs are authenticated with mutual TLS and IP allowlisting.

In this example, we assume you are a client of TxB's and want to create an API connection to perform operations on your own account(s). We also support the ability to securely perform operations on other clients' accounts where express permission is granted.

Step by Step Guide

Step 1 - IP Allowlisting

First, we need to allowlist IPs. Clients (or partner connecting on behalf of a Client) should provide TxB all of their CIDR blocks for inbound connectivity for both test and production servers.

Step 2 - Developer portal user

Clients (or partner connecting on behalf of a Client) should provide contact information like email and name of a developer user for the API certificate management. Based on the contact information received, TxB will create a developer user account to access the details and definitions of our APIs and to create and manage API users and certificates.

Step 3(a) - API application and certificate creation

TxB offers a self-serve certificate tool that allows our clients to create and manage API users and certificates.

High level steps are:

• Create and manage API accounts, known as applications, which have associated certificates and entitlements.
  • Navigate to application creation.
  • Create your application with application name, description and additional email notification recipients.
• Once your application is created you can generate certificates used to access Goldman Sachs APIs.
  • Navigate to certificate creation.
  • Download the CSR config file.
  • Run OpenSSL command to generate the public key CSR and the private key, using the CSR config file.
  • Upload the public key CSR file and submit the certificate creation request providing the certificate name and the desired expiry date.

Follow this step-by-step guide, which will provide instructions on how to generate applications and associated certificates that can be used to access Goldman Sachs APIs.

Step 3(b) - Entitlements

Once the API application and certificate has been created, send the following to TxB:

• Client Entity Name
• API Application Name and Id
• Approval Request Id

Once the above details are received, entitlements will be granted to perform one or more of the following activities: - Entity and account creation - Payments execution - Read only reporting data.

Step 4 - Use X509 + private key to test connection

Download the certificate (X509 public certificate file) and the private key (private_key.key) generated in Step 3 and use them as inputs to run the below cURL command to test the API connectivity:

curl -s -X GET "https://api.test.txb.gs.com/v1/connectivity" -v --cacert ./<certificate file> --key private_key.key

Some versions of cURL may work with the below arguments:

curl -s -X GET "https://api.test.txb.gs.com/v1/connectivity" -v --cert <certificate file> --key private_key.key

Run this cURL command if you are using a proxy:

curl -s --proxy <proxy-url>:<proxy-port> -X GET "https://api.test.txb.gs.com/v1/connectivity" -v --cacert ./<certificate file> --key private_key.key

Success will result in the below response:

HTTP/1.1 200 Connection established

HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Wed, 23 Sep 2020 12:19:27 GMT

{
    "connection”: “OK”,
    "additionalAuth": "OK"
}

Step 5 - Add a JWT (optional)

In some cases, Clients and Partners may need to provide step up authentication. Every TxB API allows you to include a JWT in the Authentication input parameter. Step up authentication may be required on certain end points or in cases where you perform an operation on a 3rd party account.

See here for step by step instructions on using our Step Up Authentication.