Key Requirements

To use the Treasury Solutions API, you will need:

• API Key: For identification and authentication.
• RSA Key Pair: For signing requests and ensuring request integrity.

Requesting an API Key

To access the Treasury Solutions API, you must first request an API key. When requesting an API key, specify the required permissions:

• Read permissions: Grants access to retrieve transactions, accounts, and counterparties.
• Write permissions: (Future functionality) Grants access to create counterparties, accounts, and make payments or conversions.

How to request:

1. Contact our support team at [email protected] or your assigned implementation manager.
2. Specify the read and/or write permissions required for your use case.
3. After approval, you will receive your API key, typically within one business day.

Generating a Key Pair

To securely sign requests, you need to generate an RSA key pair. You can generate an RSA key pair using OpenSSL or another tool of your choice.

In future iterations, we will add self-service support so you can do this via the Client Portal.

Requirements:

• Key size: 2048 bits
• Format: PEM format

Sample script to generate key pair:

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in private_key.pem -out public_key.pem

Register your Public Key

After generating your key pair, register your public key with us so we can verify your signed requests.

1. Send your public key: Determine the most secure way with your implementation manager. Ideally, passcode encrypted i.e encrypted zip file.
2. Key association: We will associate your public key with your API key, enabling us to verify signed requests made from your system.
3. Wait for confirmation: We will associate your public key with your API key, and you will receive confirmation within one business day.

Important: Please only share your public key as sharing your private key renders the key pair invalid.

Signing Requests

To ensure the integrity and authenticity of your requests, you must sign them using your private key.

1. Create the signature:

   • Concatenate the HTTP method, full resource (with any query or path parameters), and the JSON payload (if any) in this exact order.
   • Generate a SHA-256 hash of this content.
   • Sign this hash with your private key

2. Include the following headers in your API request:

   • x-api-key: Your API key.
   • x-signature: The Base64-encoded signature from step 1.

3. Request verification:
   The Treasury Solutions API server will use your registered public key to verify the signature and ensure the request is authentic and has not been altered.

4. Code samples

• Resource with Path Parameter Node.js:

import * as crypto from 'crypto';

const privateKey = `-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----`;

// Example with Path Parameter
const pathPayload = 'GET/counterparty/f9c1bcab-5268-44c8-a6d5-65054bdfa46a';
const pathSignature = crypto.createSign('RSA-SHA256');
pathSignature.update(pathPayload);
const pathSignatureResult = pathSignature.sign(privateKey, 'base64');

• Resource with Query Parameters Node.js:

import * as crypto from 'crypto';

const privateKey = `-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----`;

// Example with Query Parameters
const queryPayload = 'GET/transactions?fromDate=2024-06-26T00:52:28.795Z&toDate=2024-07-27T00:52:28.795Z&status=new';
const querySignature = crypto.createSign('RSA-SHA256');
querySignature.update(queryPayload);
const querySignatureResult = querySignature.sign(privateKey, 'base64');

• Resource with Path Parameter Python:

import base64
import hashlib
from Crypto.Signature import pkcs1_15
from Crypto.PublicKey import RSA

private_key = """-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----"""

key = RSA.import_key(private_key)

# Example with Path Parameter
path_payload = 'GET/counterparty/f9c1bcab-5268-44c8-a6d5-65054bdfa46a'
path_hash = hashlib.sha256(path_payload.encode('utf-8')).digest()
path_signature = pkcs1_15.new(key).sign(path_hash)
path_signature_base64 = base64.b64encode(path_signature).decode('utf-8')

• Resource with Query Parameters Python:

import base64
import hashlib
from Crypto.Signature import pkcs1_15
from Crypto.PublicKey import RSA

private_key = """-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----"""

key = RSA.import_key(private_key)

# Example with Query Parameters
query_payload = 'GET/transactions?fromDate=2024-06-26T00:52:28.795Z&toDate=2024-07-27T00:52:28.795Z&status=new'
query_hash = hashlib.sha256(query_payload.encode('utf-8')).digest()
query_signature = pkcs1_15.new(key).sign(query_hash)
query_signature_base64 = base64.b64encode(query_signature).decode('utf-8')