Introduction

Kompliant will issue to customers that desire access to our APIs a set of credentials. The credentials will be in the form of an API Key, a Secret Key, and an Auth Token. The access that an API key bestows will be limited to either the sandbox environment or the live environment.

API calls into our system will require the API Key, Auth Token, and an HMAC signature for authentication and authorization. The HMAC signature is generated by signing a predefined set of data using the Secret Key.

Customers have options about what data to sign with the request, allowing for better security of the APIs, such as mitigating against replay attacks or man-in-the-middle attacks.

We call this authentication protocol Kompliant Signature Version 1.

Getting Credentials

If you wish to use our APIs, you must follow the steps on the Requesting API Credentials page.

Kompliant will generate the credentials and send them securely to you. A set of credentials only work for one environment (live or sandbox) and will not work for the other environment.

The credentials consist of three parts: an API Key, a Secret Key, and an Auth Token.

All values are case sensitive.

The API Key will have a prefix of either sb_ or lv_ to indicate that the credentials are for sandbox or live, respectively.

You must keep the Secret Key confidential like you would passwords or private certificates. If you believe your credentials were compromised, you must request a new set of credentials and ask us to disable the old set of credentials.

If you lose the Secret Key or Auth Token, we cannot recover them. You will need to request a new set of credentials.

API Request Process

The process for making an API request consists of the following steps:

1. Use the Secret Key to sign the data elements that will be protected. At minimum this must be the API Key but can include other elements as outlined below in the Signing Process section.
2. Include the appropriate items the HTTPS headers. At minimum the Authorization, X-API-Key and X-API-Auth-Token headers must be included. The Headers document describes each HTTP Header in detail.

Signing Process

The signing process is critical to this authentication mechanism. The server will verify the authentication by duplicating the signing process and comparing the signatures.

While the API Key is the only item required to be signed, it is recommended that other aspects of the request also be signed. Including other parts of the request can increase the security of the request.

🚧

Not Supported Yet

Not all elements are supported yet. The following elements are not supported at this time:

• URL-Path
• Content-MD5

The following items can be included with the API Key to be signed: the HTTP verb, the URL path, the API version, a timestamp, the Content-Type header value, an MD5 hash of the content, and a nonce. Aside from the HTTP verb and URL path, each value included to be signed will need to have that value included in the corresponding header. See the Data Elements section for more information about each data element and its value.
When signing more than the API Key, each item must be included in the string to be signed but separated by a linefeed character (\n).

For example, if you are going to sign all the possible data elements then the string to sign would look like this:

API-Key + '\n' +
HTTP-Verb + '\n' +
URL-Path + '\n' +
Timestamp + '\n' +
API-Version + '\n' +
Content-Type + '\n' +
Content-MD5 + '\n' +
Nonce

Note that each element above is the string representation of the data element’s value.

Data elements being added to the string to sign must use the following order:

API-Key
HTTP-Verb
URL-Path
Timestamp
API-Version
Content-Type
Content-MD5
Nonce

For example, if you are signing the API-Key, URL-Path, and Content-MD5 then the string to sign would look like this:

API-Key + '\n' +  
URL-Path + '\n' +  
Content-MD5

The signature is calculated using the HMAC-SHA256 algorithm, with the Secret Key as the signing key. The Secret Key is a Base64 (RFC 4648) string that must be converted to bytes before being used. The string to sign must be encoded as bytes using UTF-8. The bytes outputted from the algorithm must be converted to a Base64 (RFC 4648) string.

Request Process

Once the signature is generated, the request can be sent with all the required components. The request will require certain HTTP headers to be included, depending in part, on the data elements included. A full explanation of each header can be found in the HTTP Headers document.

The Authorization header is always required and contains the string KSig1-HMAC-SHA256 followed by a space followed by the calculated signature.

The X-API-Key and X-API-Auth-Token headers are also always required and contain the API Key and Auth Token respectively.

If any optional data elements were included in the string to sign (such as URL path or a Timestamp), then the X-API-Signed-Elements header must be included. See the X-API-Signed-Elements sub-section in the HTTP Headers document for details about the format of this header.

Finally, for any of the other optional data elements, except for the HTTP verb and URL path, a header for each value is required. The HTTP verb and the URL path are already part of any HTTP request. See the HTTP Headers document to learn which header to use for each data element and, where needed, how the data element is calculated.

Aside from the headers outlined here, the rest of the request should follow normal HTTP standards and any other standards the particular API requires.