Back to Website

Articles in this section

Generate Authentication Strings (REST API)

Some REST endpoints allow performing sensitive operations such as placing orders or requesting a digital asset withdrawal. These private endpoints can therefore be called only through encrypted requests and an authentication string (authent) must be included in each such request. authent is computed from the following inputs:

PostData

postData is a "&" concatenation in the form <argument>=<value> and is specific to each REST endpoint.

Example To operate the endpoint orderbook you choose the argument symbol with value
fi_xbtusd_180615. postData is then given by symbol=fi_xbtusd_180615.

Update Authentication Flow for v3 endpoints: As of 20th February 2024, to align with best practices and ensure a higher security standard, we are going to update the authentication flow for our /derivatives/* (v3) endpoints. (details below)

PostData Generation Changes:
- Before release: Users were required to hash query string parameters before url-encoding for Authent generation, e.g., `greeting=hello world`.
- After release: The authentication process will now require hashing the full, url-encoded URI component as it appears in the request, e.g., `greeting=hello%20world`. This method enhances security and aligns with the best practices.
This update is particularly relevant for the v3 batchorder endpoint, which accepts a JSON body in its query parameters.


Backward Compatibility and Future Plans:
For the time being, this change is backward compatible. The platform will accept both PostData generation methods described above. However, we aim to phase out the old method (hashing decoded query string parameters) in the future to maintain the highest security standards. We will provide ample notice ahead of this change and strongly encourage all users to transition to the new method as soon as possible to ensure seamless service continuity.

Nonce

nonce is a continuously incrementing integer parameter. A good nonce is your system time in
milliseconds (in string format). Our system tolerates nonces that are out of order for a brief period of time. Nonce is not required.

Example      1415957147987  

Many authentication issues are related with incorrect nonce. A new pair of API keys will automatically reset the nonce and resolve these issues.

Endpoint Path

endpointPath This is the URL extension of the endpoint.

Example      /api/v3/orderbook  

 

API Secret

The api_secret is obtained as described in the previous section.

Example rttp4AzwRfYEdQ7R7X8Z/04Y4TZPa97pqCypi3xXxAqftygftnI6H9yGV+O
cUOOJeFtZkr8mVwbAndU3Kz4Q+eG

Based on these inputs, authent needs to be computed as follows:

  1. Concatenate postData + nonce + endpointPath
  2. Hash the result of step 1 with the SHA-256 algorithm
  3. Base64-decode your api_secret
  4. Use the result of step 3 to hash the result of the step 2 with the HMAC-SHA-512 algorithm
  5. Base64-encode the result of step 4

 

Example    
 

The following shows an implementation of authent in Java. For full working examples in different programming languages, see Section Additional Resources.

public static String getAuthent(String postData, String nonce, String endpointPath, String secretKeyBase64)
{
        Mac mac512;
        MessageDigest sha256;
        try {
                 SecretKey secretKey = new SecretKeySpec 
                       (Base64.decode(secretKeyBase64.getBytes()), HMAC_SHA_512);
                 mac512 = Mac.getInstance(HMAC_SHA_512);
                 mac512.init(secretKey);
                 sha256 = MessageDigest.getInstance("SHA-256");
         } catch (IOException e) {
             ...
         } catch (InvalidKeyException e) {
             ...
         } catch (NoSuchAlgorithmException e) {
             ...
         }

         sha256.update(postData.getBytes());
         sha256.update(nonce.getBytes());
         sha256.update(endpointPath.getBytes());
         mac512.update(sha256.digest());
         return Base64.encodeBytes(mac512.doFinal()).trim();
}