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. This is essential for you to execute the cURL command in Step 4

Step 2 - User creation & entitlements

TxB will then create for you a Client identifier (gseid) and an API User identifier (gsuid). Each API User will also be granted entitlements to perform one or more of the following activities: - Entity and account creation - Payments execution - Payments execution for internal transfers - Payments execution to predefined set of beneficiaries - Read only reporting data

These identifiers will be used in the CSR generation process in Step 3

Step 3 - Certification creation & exchange

You can now generate a CSR request using a preset template file provided by TxB. The CSR request template looks like the below and the Client is asked to fill out the section titled [ dn ].

[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn

[ dn ] #Client to modify this section with appropriate details
C=US
ST=New York
L=New York
O=GSTxB
OU=xyzTsySvcs
emailAddress= xyzTsySvcsuser@no-email-address.domain.com
CN = xyzTsySvcs.domain.com

[ req_ext ]
subjectAltName = @alt_names

[ alt_names ]
URI.1 = gseid://0EAA62456B3426NU962A296BC4C5F9C9 #replace 0EAA62456B3426NU962A296BC4C5F9C9 with gseid from Step 2
URI.2 = gsuid://001df87sdfd7f8f999s9ded60126a299 #replace 001df87sdfd7f8f999s9ded60126a299 with gsuid from Step 2

Save the above as text file(e.g., template.txt) and execute the openSSL command as below:

openssl req -new -sha256 -nodes -out public_key.csr -newkey rsa:2048 -keyout private_key.key -config template.txt

This script produces two files:

1. public_key.csr - send this file to TxB. We will use it to generate X.509 file (e.g.,certificate.pem)
2. private_key.key - DO NOT SHARE THIS FILE WITH TXB

Step 4 - Use X509 + private key to test connection

Take the two outputs of Step 3 (1. certificate.pem and 2. private_key.key) and use them as inputs to run the below cURL command:

curl -s -X GET "https://api.test.txb.gs.com/v1/connectivity" -v --cacert ./certificate.pem --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.pem --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.pem --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.