When 1o issues HTTP requests to Merchant Integrations, the tokens are generated along the same guidelines as described in the 1o ⇠ Merchant section. Take the time to read that first. The following section will describe the same process from the opposite perspective, so a few key points will be repeated.
In order to integrate with 1o correctly, an integrator must verify that the requests are indeed coming from 1o and have not been tampered with. We will now describe the authentication process from the perspective of an integrator (the receiver of the HTTP request).
The authentication process is based on PASETO tokens.
<aside> 💁 We can’t overstate how important it is to use an existing library (if available) to implement the process described in this section instead of implementing the algorithm yourselves.
</aside>
HTTP requests sent by 1o to integrators will include an Authorization header in the following format: Authorization: Bearer TOKEN. Let’s look at an example:
Authorization: Bearer v2.local.qwfi6mZ_xiom0Lz9dztkZ6p-_uXD06sb6DDHAe0UQbZbg7ESXD-h_izsciKQrR8P_WmrtQENAR4acJ0FEXpPUjEcUPwuYtYzKrqiS-naLkrNr-H2VWxDpQa8Zw2YtKBjM_aD.IntcImtpZFwiOlwiMGEzMTU2NjAtNGJiNy00MjI4LTk0MDgtZjQzMDA3MzMwNjZmXCJ9Ig
In order to read the token we drop the Bearer prefix. What remains is a PASETO token:
v2.local.qwfi6mZ_xiom0Lz9dztkZ6p-_uXD06sb6DDHAe0UQbZbg7ESXD-h_izsciKQrR8P_WmrtQENAR4acJ0FEXpPUjEcUPwuYtYzKrqiS-naLkrNr-H2VWxDpQa8Zw2YtKBjM_aD.IntcImtpZFwiOlwiMGEzMTU2NjAtNGJiNy00MjI4LTk0MDgtZjQzMDA3MzMwNjZmXCJ9Ig
PASETO tokens consist of three or four segments (in our case we will be working with four) separated by a period:
version.purpose.payload.footer
When decoding a token, we start by verifying the version and the purpose. The version must equal to v2 and the purpose must equal to local.
<aside> ‼️ If the token does not match these two constraints we must reject the token as invalid.
</aside>
The footer is a Base64-encoded JSON object. Continuing with the above example, the footer is:
IntcImtpZFwiOlwiMGEzMTU2NjAtNGJiNy00MjI4LTk0MDgtZjQzMDA3MzMwNjZmXCJ9Ig
After base64-decoding:
{"kid":"0a315660-4bb7-4228-9408-f4300733066f"}