How Does Trolley’s API Authentication Work?

In this post, we look deeper into how we verify incoming API requests and what different error messages mean. This post will help you better understand and avoid authentication errors.

Trolley APIs process thousands of requests every second, and all these requests have unique authentication signatures. To make sure the request is really coming from you, we verify each request using a custom authentication scheme that requires developers to compute a new signature every 30 seconds. Moreover, our SDKs based on top of our APIs also depend on this authentication scheme.

In this post, we’ll explore how our authentication works and how we verify these requests.

To explain how the Trolley authentication process works, we’ll go over a sample cURL request step by step, describing how the verification of requests works. We’ll also detail the errors that might be generated at different steps, what they mean, and what you can do to fix them.

Let’s begin.

Authentication explained: A sample cURL request  

Our API documentation  details how our authentication works, along with sample codes in 6 programming languages.

Using the sample code provided, here’s a sample cURL request we’ll be using to illustrate our authentication.

The API request in this sample is a POST API call to fetch an invoice:

curl --location 'https://api.trolley.com/v1/invoices/get' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: prsign ALC7AsydVIH2FB2AEIC:cd41d2da4158b3ba19c245176091a81ef4d9c40d2cab8' \
  --header 'X-PR-Timestamp: 1709586704' \
  --data '{
    "invoiceId": "I-MBS3YHDhkzKZo76c7fvscG"
  }'

In this sample request, notice the value of the Authorization header. It contains the authentication scheme being used (prsign) followed by the Access Key and request signature in the following pattern:

Authorization: prsign <ACCESS_KEY>:<SIGNATURE>

We’ll use this reference further in the article.

Step 1: Confirm the timestamp  

When we receive a request, we first check whether it was made in the last 30 seconds.

To verify that, we check the value of the X-PR-Timestamp header in the request.

If this verification fails, users will receive the following error:

{
	"ok": false,
	"errors": [
    	{
        	"code": "invalid_api_key",
        	"message": "Timestamp is more than 30 seconds off of server time"
    	}
	]
}

The message part of this error message highlights that the timestamp is off.

The most likely cause for this is that the server’s time is out of sync or the request is stale, possibly because of caching.

To fix this, make sure the clock of the client sending this request is synchronized correctly.

Additionally, one should ensure the client is not sending requests in a way that the signatures are re-used or cached.

Step 2: Confirm that the Access Key is correct  

After verifying the timestamp, we check if the API key is valid.

To pick the ACCESS_KEY from the request, we use the value of the Authorization header and take the <ACCESS_KEY> part from it, as shown in the sample above.

If the API ACCESS_KEY found in the request doesn’t exist in our databases, we return the following error:

{
	"ok": false,
	"errors": [
    	{
        	"code": "invalid_api_key",
        	"message": "Invalid token: not found keyPrefix=ALC7Aabcd12"
    	}
	]
}

If you receive this error, check the merchant dashboard to ensure the ACCESS_KEY being used exists.

Please note the API Keys are different for production and sandbox environments. So, when investigating API Keys, be sure to review both environments.

Step 3: Verify the request signature  

After passing the above two validations, we check if the request signature is valid.

To do this, we recreate the request signature on our end and then compare it with the <SIGNATURE> value that you sent in the request’s Authorization header, as shown in the reference above.

To recreate the request, we use the existing knowledge from the request—request type, request path, request body—and then take the timestamp information from the X-PR-Timestamp header.

With this information, we recreate the message, which we hash with the SECRET_KEY to create the signature.

For the sample request shared above, these values will be:

$message = “1707192470\n
POST\n
/v1/invoices/get\n
{
	"invoiceId": "I-MBS3YHDhkzKZo76c7fvscG"
}"

Then, this value is hashed using the SECRET_KEY fetched from our database and compared with the signature sent in the request.

If these signatures don’t match, we return the following error:

{
	"ok": false,
	"errors": [
    	{
        	"code": "invalid_api_key",
        	"message": "Invalid token: bad hash"
    	}
	]
}

If you receive this error, make sure that the signature is being created correctly.

Our API documentation  provides sample code to generate authentication signatures in 6 different programming languages.

These samples should help you understand how to write code to implement Trolley’s authentication.

Conclusion  

We hope that the explanations in this blog post clear up any confusion surrounding how API requests are verified on our end and help you avoid or mitigate authentication errors.

If you encounter any issues, please don’t hesitate to write to us at developers@trolley.com.