Skip to main content

Splitit Side: Signature Verification for API Responses

You may wish to definitively verify that responses from the Splitit APIs originated from the Splitit APIs. In order to do this, you can request that Splitit API responses be signed. In this process, Splitit uses a private key to sign responses, which you can then verify originated at Splitit by implementing the corresponding public key.

Things to know:

  • Supported by API V3 only
  • You can choose to receive Splitit's signature either in a header or in an embedded JWS format
  • For the sake of debugging and support, please preserve the response header x-splitit-traceid

Instructions​

  1. Begin by authenticating to the Splitit ID server, using the instructions here. You'll receive a bearer token in the response.
  2. Add the bearer token from step 1 in your header, then call Generate Key Pair. The body to send is as follows:
{
  "Type": "RSA",
  "Usage": [
    "ResponseSignature"
  ],
  "OwnerCode": "string" // given to you by Splitit support
  "ExpirationUtc": "2024-07-06T15:46:26.409Z", // when you'd like your key to expire (if you don't set this, a default value will be set by Splitit)
  "RelatedClientId": "string" //the client from  your account you'd like to use; given to you by Splitit support
}

You will receive a public key in return along with its corresponding Key ID.

  1. Perform a request on any API V3 endpoint, making sure to attach:

    • your bearer header from step 1
    • a potential additional token (depending on your integration)
    • the optional header X-Splitit-ResponseSignature-Mode: jwt, which specifies that you'd like to receive the signature back in embedded JWS format rather than in the headers

  2. Receive a response from Splitit, which will differ depending on whether you requested the signature in headers (default) or in the body:

    Default (in headers)​

    You will receive the following headers:

    • X-Splitit-ResponseSignature-KeyId - The id of the key used to sign the response (if you have generated more than one key with the same Usage, the key that Splitit will use from your account is the one that has the latest expiration date)
    • X-Splitit-ResponseSignature-Token - nonce token used to enhance security in case of an empty body response
    • X-Splitit-ResponseSignature - the actual signature


    Embedded (signature in JWS format embedded in body)​

    The actual signature (including its headers with Key ID) will arrive encoded in the body.

    Note that if you have elected to receive your Splitit responses encrypted with MLE, the signature will be nested, i.e. the payload for your JWS will be JWE instead of plaintext.

  3. Verify that the message was sent from Splitit using the signature and the public key from step 2.