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:
- Concatenate the values included in your request based on the list and order described on the Fingerprint order page.
- Calculate the SHA512 hash of the concatenated string. This is the value of the
X-Soldo-Fingerprint
header of the request.- 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
andX-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 thefromDate
andtoDate
parameterscategory
to determine the category transactions should be filtered bystatus
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:
Order | Field | Value |
---|---|---|
1 | type | |
2 | publicId | |
3 | customReferenceId | |
4 | groupId | |
5 | fromDate | 2024-01-01 |
6 | toDate | 2024-02-01 |
7 | dateType | SETTLEMENT |
8 | category | Payment |
9 | status | Settled |
10 | tagId | |
11 | expenseType | |
12 | expenseStatus | |
13 | text | |
14 | token | QDX6RK6OH1CZLSWOUWBA |
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 theQDX6RK6OH1CZLSWOUWBA
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
.
Updated 8 months ago