REST authentication#

Make requests#

All private REST requests must contain the following headers:

• OK-ACCESS-KEY The API key as a string (follow this guide to generate an API key)
• OK-ACCESS-SIGN The Base64-encoded signature (go to the Signature subsection for details)
• OK-ACCESS-TIMESTAMP The UTC timestamp of your request, e.g., 2020-12-08T09:08:57.715Z
• OK-ACCESS-PASSPHRASE The passphrase you specified when creating the API key

Some endpoints, such as WaaS, require an additional header:

• OK-ACCESS-PROJECT The project ID of your project (can be found under project details)

Request bodies should have content type application/json and be in valid JSON format.

Signature#

The OK-ACCESS-SIGN header is generated as follows:

• Create a prehash string of timestamp + method + requestPath + body (where + represents string concatenation)
• Prepare the secret key (generated when you create an API key)
• Sign the prehash string with the secret key using the HMAC SHA256
• Encode the signature in the Base64 format

Example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC', SecretKey))

• The timestamp value is the same as the OK-ACCESS-TIMESTAMP header with millisecond ISO format
  • Example: 2020-12-08T09:08:57.715Z
• The method should be in UPPERCASE
  • Example: GET and POST
• The requestPath is the path for requesting an endpoint
  • Example: /api/v5/account/balance
• The body refers to the string of the request body. It can be omitted if there is no request body (frequently the case for GET requests).
  • Example: {"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
  • Note: GET request parameters are counted as requestpath, not body

Postman example#

Postman is a popular API development and testing tool that allows developers to design, test, and document APIs. It provides a user-friendly graphical interface for making HTTP requests to APIs.

If you have not installed Postman, you can download it for free from the Postman website: https://www.postman.com/

Add parameters#

• This typically applies to GET requests.
• If your request requires query parameters, you can add them under the Params tab. Here, you can add key-value pairs for your query parameters.

Set headers#

Under the Headers tab, add the following key-value pairs:

• OK-ACCESS-KEY
• OK-ACCESS-PASSPHRASE
• OK-ACCESS-PROJECT (if required)

Add body#

• This typically applies to POST requests.
• If your request requires a request body, you can add them under the Body tab.
• Select raw and JSON under the dropdown menu.
• Input your request body in JSON format.

Set pre-request script#

• This is used to generate the necessary signature (OK-ACCESS-SIGN) and timestamp (OK-ACCESS-TIMESTAMP)
• Under the Pre-request Script tab, insert the script which corresponds to the request type.
• Exclude the request body when generating the prehash string for GET requests.
• Edit the secret key accordingly.

GET requests:

var method = pm.request.method;
var now = new Date();
var isoString = now.toISOString();
var path = pm.request.url.getPathWithQuery();
var sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(isoString + method + path, pm.variables.replaceIn('{{secret_key}}')));

pm.request.headers.add({
    key: 'OK-ACCESS-SIGN',
    value: sign
});

pm.request.headers.add({
    key: 'OK-ACCESS-TIMESTAMP',
    value: isoString
});

POST requests:

var method = pm.request.method;
var now = new Date();
var isoString = now.toISOString();
var path = pm.request.url.getPathWithQuery();
var bodyStr = pm.request.body.raw;
var sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(isoString + method + path + bodyStr, pm.variables.replaceIn('{{secret_key}}')))

pm.request.headers.add({
    key: 'OK-ACCESS-SIGN',
    value: sign
});

pm.request.headers.add({
    key: 'OK-ACCESS-TIMESTAMP',
    value: isoString
});