For live clients absolutely all requests should be signed. For the clients with other statuses, it is optional:

  • If the signature headers aren’t sent, the request will be performed without any signature validations;
  • If the signature headers are sent, the request signature will be verified.

Before all, service clients should provide their public key by inserting it’s content in security page.

The private key should be securely stored on your server.

In case of possible security breach, the private key should be regenerated and the public key should be updated in your profile.

Signature headers

For a better understanding of how to adapt the corresponding headers in your application, take a look at the sample applications for platforms such as:

The following headers are required for your request to be considered signed:

  • Expires-at - request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time. The maximum value is 1 hour from now in UTC, otherwise ExpiresAtInvalid error will be raised;
  • Signature - base64 encoded SHA1 signature of the string represented in the form Expires-at|request_method|original_url|post_body|md5_of_uploaded_file| - 5 parameters concatenated with a vertical bar |, signed with the client’s private key.

The pseudocode to generate the signature looks like this:

base64(sha1_signature(private_key, "Expires-at|request_method|original_url|post_body|md5_of_uploaded_file|")))

The fields request_method, original_url, post_body and md5_of_uploaded_file from the Signature header represent:

  • request_method - uppercase method of the HTTP request. Example: GET, POST, PATCH, PUT, DELETE, etc.;
  • original_url - the full requested URL, with all its complementary parameters;
  • post_body - the request post body. Should be left empty if it is a GET request, or the body is empty;
  • md5_of_uploaded_file - the uploaded file digested through MD5 algorithm. Should be left empty if it is a GET request, or no file uploaded.

An example of the string that is to be used to generate the signature looks as follows:

  • GET string example: 1413802718|GET||;
  • POST string example (without file): 1413802718|POST||{"data":{"identifier":"my_unique_identifier"}};
  • POST string example (with file): 1413802718|POST||{"data":{"identifier":"my_unique_identifier"}}|6979a174280bdf7319940c59fabbd2b8|.

Headers example:

Expires-at: 1413466421
Signature: 0o6LgMnlG7FX5tWLoKd6V5jlktodP8I/3vWqh1pOZvPgMn/WPq5YqZWPc0teey135RO2muFThcvuZJtcbaUje1UWFHyWhTh89guHJ47pgBB7w0LMkRw3XskEsafEUZketeTY/NtyeU7ETHHm2Tlw8IJho+gk51Rtp7JJPanw2OZG/6BElFcL0qGs4ohTmJUKKsdI1eo5jseFqF+sX0T4dRYqL7ebhDCD8YsYdsZ9zxlX88+YtUQnEqGbswOH4saGaQNH9NjxST2NS8MFtCU7uwZGybBk4i0l1wtbTJwfgaa+yb2L7l0ltIgxZFJzQOShpVOgI+o8fUg31lOblmMVkpyvXJ/n5Ed2u0nA1yMWkQUPpu03Xkh2RG7qbBOEq6+A374OnhUDwi5TUqYrY89paPwq/A7z2lc56Q84T+NrSLdi0x0aejpp6Cn90Yqpbs04dIio579+KyLm/8XoZ4p9k7vz6vTpDITyTAc93/KHnqeT1hTp7AWMaxuGfEI361fyZLDzkSvnHq4QzMkJOKhPELxSji99dm0LCSZpUiUhTTU3G09LvLBCEFLvbGJzxlO7NgqOGVPMlEc4fJqzU/jrTfkodn4DtzaOJghlXynithKIUBAkpNY9QGPOQIMvcbOZfhilm+bjWuYeNpeALvbqY3ONcibHLjc8ItAVMzORSFg=

RSA keys generation instruction

1) Install openssl package

Mac OS X

Install via Homebrew: brew install openssl


Windows complete package .exe installer

Ubuntu Linux

apt-get install openssl

2) Create the RSA Key Pair

  • for Mac OS X and Ubuntu Linux:

    type in the command line:

    openssl genrsa -out private.pem 2048
    openssl rsa -pubout -in private.pem -out public.pem
  • for Windows:

    After the package has been installed, a folder with name: OpenSSL-Win32 should appear at the install path.

    Next, open a Command Prompt and change your current directory to this folder by typing:

    cd C:\OpenSSL-Win32\bin, where C:\OpenSSL-Win32 should be replaced with the install path.

    Then you can generate RSA keys by typing:

    openssl genrsa -out private.pem 2048
    openssl rsa -pubout -in private.pem -out public.pem

    and follow the instructions that appear afterwards

Possible errors

The possible errors that may appear from validating the signed requests: