This document describes each of the data elements that can be included in the string to sign. Every data element should not have leading or trailing whitespace.

API-Key

The API-Key is the API Key that was issued as part of the credentials. It is a string with a prefix of either sb_ or lv_ to indicate that the credentials are for sandbox or live, respectively.

The value is required to always be signed.

The value is case sensitive.

The value must be included in the X-API-Key header.

HTTP-Verb

The HTTP-Verb refers to the HTTP method being used. Allowed values include GET, POST, PUT, DELETE, PATCH. However, individual API methods may limit the allow methods further.

The value must always be uppercase.

Including this data element ensures that the verb cannot be changed by a bad actor, such as changing the verb from GET to DELETE.

URL-Path

🚧

Not Supported Yet

The URL-Path element is not supported yet as part of the signing process.

URL-Path is the path and query string (if any) after the host name, including the leading forward slash.

For example the following URL

https://api.kompliant.com/apply?pmid=35c183fe-7dc8-44e5-bd57-1a12047f922a

the URLPath is

/apply?pmid=35c183fe-7dc8-44e5-bd57-1a12047f922a

The value is case sensitive.

Including this data element ensures that a bad actor cannot change the URL path, such as a GET request from
/application/123
to
/application/456.

Timestamp

The Timestamp is the Unix timestamp of when the request is created. The value is the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC. An example is 1724710669.

If this data element is included in the string to sign, the value must be included in the X-API-Timestamp header.

Including this data element ensures that a bad actor cannot replay prior requests after a small time window.

🚧

Partially Supported

While a Timestamp data element can be included in the string to sign, the system does not check the timestamp value to ensure that the message has not expired.

API-Version

The API-Version is the string used in the optional X-API-Version header to indicate to the server what version of the API you are using.

The value is case sensitive.

If this data element is included in the string to sign, the value must be included in the X-API-Version header.

Including this data element ensures that a bad actor cannot change the API version of a request, such as a GET request using different versions of the API.

Content-Type

The Content-Type data element corresponds directly to the Content-Type header. This is typically used to tell the server what type of data is being included in the request, such as for a POST request. The allowed values for the Content-Type header are defined by the particular API method.

The value is case insensitive, but lowercase is preferred.

If this data element is included in the string to sign, the value must be included in the Content-Type header.

Including this data element ensures that a bad actor cannot change the way a server will process the payload.

Content-MD5

🚧

Not Supported Yet

The Content-MD5 element is not supported yet as part of the signing process.

The Content-MD5 data element is the hexadecimal representation of the MD5 hash of the request body. The hash must be calculated on the request body as it will appear in the HTTP request. Leading and trailing whitespace must be removed from the request as a whole. Whitespace can be included within the request.

As example, if the request body is a JSON string as shown here:

{  
  "application": {  
	"id": 1,  
	"created_date": "2024-08-09T12:59:37",  
	"status": "SUBMITTED"  
  }  
}

The calculated MD5 hash is

27c88dca0b70a5a2bfd5e1ea516373b1

The value is case insensitive, but lowercase is preferred. The value must not contain spaces.

If this data element is included in the string to sign, the value must be included in the X-API-Content-MD5 header.

Including this data element ensures that a bad actor cannot change the payload of a request.

Nonce

The Nonce data element is a random positive integer up to 128 bits in size. To be of benefit, a new Nonce should be generated for each request.

If the Nonce data element is included in the string to sign, then the Timestamp element must also be included.

If this data element is included in the string to sign, the value must be included in the X-API-Nonce header.

Including this data element, along with the Data-Time-Value element, ensures that a bad actor cannot replay a previously sent request.

🚧

Partially Supported

While a Nonce data element can be included in the string to sign, the system does not check if the nonce has been sent before.