Advanced authentication

Completing advanced authentication

📘

Before you begin

Before you can complete advanced authentication, you'll need to share your public 2048 RSA key (format X.509 SubjectPublicKeyInfo/OpenSSL PEM public key) with Soldo. You can learn how to create one here.

Depending on the type of request you're making, standard authentication may not be enough, and an additional layer of security might be required. This additional security layer is called advanced authentication, and consists of two Soldo headers that must be included with the request. These are:

• X-Soldo-Fingerprint This contains the hash of a string made of multiple values included in your request, concatenated together in a specific order. The SHA-512 hashing algorithm should be used, and the hashed string must be all in lower case. The list of fields to be concatenated for each request and their order can be found on the Fingerprint order page.
• X-Soldo-Fingerprint-Signature This contains the signature of the X-Soldo-Fingerprint value you previously calculated. The signature algorithm is SHA512withRSA and the signed value must be encoded in Base64. To sign the fingerprint, you'll need to use the private key that corresponds with the public key you uploaded to the Soldo web app when setting up the API.

Let's look at an example

📘

TL;DR

Here's how to calculate the values for the advanced authentication headers:

1. Concatenate the values included in your request based on the list and order described on the Fingerprint order page.
2. Calculate the SHA512 hash of the concatenated string. This is the value of the X-Soldo-Fingerprint header of the request.
3. Sign the fingerprint calculated in the previous step with the private key that corresponds to the public key you uploaded to the Soldo web app when setting up the API. The signature algorithm is SHA512withRSA and the signed value should be encoded in Base64. This is the value of the X-Soldo-Fingerprint-Signature header of the request.

The example below shows how to calculate the advanced authentication header values in order to successfully make the request:

# Search all the payment transactions settled in January 2024

curl --request GET \
     --url 'https://api.soldo.com/business/v2/transactions?fromDate=2024-01-01&toDate=2024-02-01&dateType=SETTLEMENT&category=Payment&status=Settled' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}'
     --header 'X-Soldo-Fingerprint: 2681a9bc561c7458c48cbb959b2aa0728688d45e635eb27f0137fca326b4e4370431cf88b51fc131d6a6adbf770beabf56bf8ebd7b6c3bb9590e2707ff04425e'
     --header 'X-Soldo-Fingerprint-Signature: fm0y1PBaOfS9wcq3N8OqkD8tMyy9x1weJAb224UMFaY+56xwCWI3jEDYLmyvbE+FJ1PkfL1OQR+pnQ8bm1yCXp2FLAFl64GaCaCrJMt1GMIQgHPh3i+gyS+MtvAYIALpC7oBkeyKsb3Aqz4wl8dBdTNcQAIwN3ZKfURNJ939xHf7VecoDpuGVncgmDHmL/I7LfVnMosRbG9AY7xgMa9sxLIw0E02JagBzIOuAjklf72rOSInxOlJtioqB5LAECE2gBrq0yBpu8tfontScVXYYhNxMLL8FUkJRKvFphIpnQ/WIpyEIrNpTOqeDMsKuv7KDGBdwOZAm5qji4CzyXaTBg=='

⚠️

Remember

This is just an example. You'll need to calculate the values of the X-Soldo-Fingerprint and X-Soldo-Fingerprint-Signature headers according to your request, and replace {access_token} with the access token you received when completing standard authentication.

Now, let's look at the above steps in more detail.

1. Concatenate the values

To get the list of all transactions settled in January 2024, we need to make a GET request against the transactions endpoint with a few query parameters:

• fromDate to define the beginning of the search, fromDate included (i.e. greater than or equal to)
• toDate to define the end of the search, toDate included (i.e. less than)
• dateType to determine the type of date to be considered for the fromDate and toDate parameters
• category to determine the category transactions should be filtered by
• status to determine the status transactions should be filtered by

Based on the query parameters above, the resulting request URL would be:

https://api.soldo.com/business/v2/transactions?fromDate=2024-01-01&toDate=2024-02-01&dateType=SETTLEMENT&category=Payment&status=Settled

According to the Fingerprint order page, the list of fields to be concatenated and their order for the search transactions request is:

type, publicId, customReferenceId, groupId, fromDate, toDate, dateType, category, status, tagId, metadataId, expenseType, expenseStatus, text, token

By mapping each fingerprint order field with the values included in our request (case sensitive), we get the following:

📘

Fingerprint token

The fingerprint token is an additional piece of information required to calculate the value of the X-Soldo-Fingerprint. You'll need to replace the QDX6RK6OH1CZLSWOUWBA sample value with the value of the fingerprint token you received while setting up the API.

By concatenating each value according to the fingerprint order, we get the following string:

2024-01-012024-02-01SETTLEMENTPaymentSettledQDX6RK6OH1CZLSWOUWBA

2. Calculate the SHA512 hash

Once we have the concatenated string from the previous step, we can calculate its hash with the SHA512 algorithm. The final string (all in lower case) is shown below. This is the value of the X-Soldo-Fingerprint header of the request.

2681a9bc561c7458c48cbb959b2aa0728688d45e635eb27f0137fca326b4e4370431cf88b51fc131d6a6adbf770beabf56bf8ebd7b6c3bb9590e2707ff04425e

✅

Success! The X-Soldo-Fingerprint header value has been calculated.

3. Sign the fingerprint

To calculate the value of the X-Soldo-Fingerprint-Signature, we need to sign the value of the X-Soldo-Fingerprint header calculated in the previous step with the private key that corresponds to the public key we uploaded to the Soldo web app when setting up the API.

Here's the private key we're going to use for this example:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAlfEt1Z6/W8ccp2FcgujAffWHeAVZClXjaejxi1SBYHSf9bPq
aPcQoWjf+TWVSkAFOIBI+d0yyc6lAcyfwTGhJdQXwdHxHOVXlFisUj2PqMlMOafv
AqAoIq2oLTSoDSK1KnPWhIS+uakN0RNukkqY8kNTrA+7FAEymzqhRwM5g8iHvHgi
iu1MSXmX9r2J1N9S3di6Mtsq1FR06PuYaBswlfkH2M4ufqll0bRLp2D31SWwEeuJ
bOp1bMdX0efldN0OjXP9+O3ngLQFkL1tStuSxI6eiyLNCAGOMyKR+NJbD8NvMNgw
Kmwyn0hDDKTMHTl/0luzOYjZouOeoWxI4RwjOQIDAQABAoIBACjPLIdgnnpvNdhE
gnZKvOFLayR6aCKM/8k6kks2o8PJ2iN4ZUtOOyODNLpSICDGTeVz3OjMkF8ms/hK
Zgyh4lc2Y4ToC/SuYujIPZZglPH+X5WtpDqVtnbBxu0O0NJKaP516qPEsVg8r7sA
y+5bCUeelW5WFbe7H7fp/C0krom0JLoa3Xg2bTEFwIpGX9t1m0Z+FstB7gAKYi6H
eu3Q2KumkRepW6vf2JGyOrtHhR9AVLVRfr+0/4oo0jT3eIqZYc0aF8KD6g4pccw+
Phefn9+17N5txTqjcU4k1UvL2TVpzIsI55zMj8SQgb7YDmGFEdkjHEHmOkLc+M0l
Clh8wOUCgYEA7fRNhybDRgmszUvUd10V2uf9DUn0sPlC2dKy0QL489LZraTo/6+I
fh8mCvebjIu8YTDc8F1JgexgUF2fK1VsNcHED8MKWkjExgT+bA4E32ID4EN0HGHG
tvMR7wqoVEundBnJKtqYquOYhPrl5DHkRbUfwrcYdod1s/q5c9u98/cCgYEAoVAw
H9UIAQEU6u5S6uppSLYoaZfQfBhY3HoUdWWRSaEErOHlDIS0e3W4OgjD9ri4bqyc
d+PmtrBnxSod2YnruXyQrGWhAbbQqg7Wo1j5GIUeiKe30qwpebkUphQqrBXNRieH
T78cVKqPdb5cwy8KQp9AT63C5UQOm8jCMj7Gdk8CgYAkNdoaZ/6tSMmgEBsL8wFh
Z44tmISA7d2LcjG99rrVt89iSkceqaKWtry+TIHCOH15OMtWVIvcFpFtiWGwYXZv
E8Z3M5H+vTYcgCQLY3LAX5UBaqJfs01fB8xB2RhWg5C+7TGcsNksoCfUjK2xNRps
tSxZIC27089IjS3tgJH+bwKBgFPUok3InbI357D3TWv7id9ZmsLVPGlhFbzuTHd9
4vUKkq1tb2UECe8nDChMqdorwNzzIxVDAIDsR+E0s/J7NF9elqig3/1ODj5yG6Uj
9b+CXo3R6zu2cI9rWYm9bTek1NqibDVLMePmB0u/M+HTLlfU/szpliEjLxxSRmlq
KiUNAoGBAMlRSpLbbyig2iu3G4hH7lFS8xInsaz/zSx4flrODY0+TyuI5d7vwUx/
DYXUA7n7vVv6ffxM/3VqEWu4daikNsWOsJyhttk4nj9ONWepV0NEH81tEOAJUb9T
YVzGpiee5GnESlt3odSUZex0zpiYFBxPe9RuYM377ju8ZZasw9QT
-----END RSA PRIVATE KEY-----

By signing the value of the X-Soldo-Fingerprint with the SHA512withRSA algorithm and encoding the signature in Base64, we get the string shown below. This is the value of the X-Soldo-Fingerprint-Signature header of the request.

fm0y1PBaOfS9wcq3N8OqkD8tMyy9x1weJAb224UMFaY+56xwCWI3jEDYLmyvbE+FJ1PkfL1OQR+pnQ8bm1yCXp2FLAFl64GaCaCrJMt1GMIQgHPh3i+gyS+MtvAYIALpC7oBkeyKsb3Aqz4wl8dBdTNcQAIwN3ZKfURNJ939xHf7VecoDpuGVncgmDHmL/I7LfVnMosRbG9AY7xgMa9sxLIw0E02JagBzIOuAjklf72rOSInxOlJtioqB5LAECE2gBrq0yBpu8tfontScVXYYhNxMLL8FUkJRKvFphIpnQ/WIpyEIrNpTOqeDMsKuv7KDGBdwOZAm5qji4CzyXaTBg==

✅

Success! The X-Soldo-Fingerprint-Signature header value has been calculated.

Potential errors

Depending on the scenario, there are different types of errors that could occur during the standard authentication process. These include:

Invalid X-Soldo-Fingerprint (INVALID_FINGERPRINT)

# HTTP Status code: 400 Bad Request

{
    "error_code": "INVALID_FINGERPRINT",
    "message": "invalid fingerprint"
}

If the request header X-Soldo-Fingerprint is missing or contains an incorrect value, the server will return a 400 HTTP status with the error code INVALID_FINGERPRINT.

To troubleshoot this error, try:

• verifying that the values concatenated to create the fingerprint correspond to the values included in your request. The list of fields to be concatenated and their order differ from request to request. They must match the fields and order listed on the Fingerprint order page of your request.
• making sure the hashing algorithm used to calculate the hash of the concatenated strings is SHA-512. The value of the X-Soldo-Fingerprint must be all lower case.
• checking that the request header name is X-Soldo-Fingerprint.

Invalid X-Soldo-Fingerprint-Signature (INVALID_FINGERPRINT_SIGNATURE)

# HTTP Status code: 400 Bad Request

{
    "error_code": "INVALID_FINGERPRINT_SIGNATURE",
    "message": "invalid fingerprint signature"
}

If the request header X-Soldo-Fingerprint-Signature is missing or contains an incorrect value, the server will return a 400 HTTP status with the error code INVALID_FINGERPRINT_SIGNATURE.

To troubleshoot this error, try:

• verifying that the value you're signing corresponds to the value included in the X-Soldo-Fingerprint request. The signature must be made using the private key that corresponds to the public key you uploaded to the Soldo web app when setting up the API.
• making sure the signature algorithm used to calculate the signature of the X-Soldo-Fingerprint value is SHA512withRSA and the signed value is encoded in Base64.
• checking that the request header name is X-Soldo-Fingerprint-Signature.