To make a call to the API endpoint, you can authenticate using a token or an API key.

Token authentication (REST, gRPC, WebSocket)

A JWT token is obtained after a successful login using a user’s credentials and MFA.

It is sent along the request, for example for REST API call, it is sent in the headers: Authorization: Bearer <JWT token>

API Key authentication (REST)

An API key is linked to a particular user and has the exact same rights the user has. It is recommended to create dedicated users, to avoid API keys being suddenly disabled once a user is deleted.

The API Key authentication Authorization: TDXV1-HMAC-SHA256 is transformed to an equivalent token authentication Authorization: Bearer <JWT token>

Format

Authorization: TDXV1-HMAC-SHA256 ApiKey=<api_key> Nonce=<uuid> Timestamp=<utc_timestamp_in_ms> Signature=<base64_signature>

Authorization field
Scheme	Must be: `TDXV1-HMAC-SHA256`
ApiKey	Contains the API key, generated by a user Example: "fcebf5ef5-69d3-4a37-b1d3-69fd462cf54c"
Nonce	Client generated random nonce: - uuidv4 - each nonce can be used only once within a timeframe of 150 seconds. Example: "f93c979d-b00d-43a9-9b9c-fd4cd9547fa6"
Timestamp	Request departure timestamp UTC in milliseconds. If timestamp is more than 150 seconds from current server time, it will not allow to make the request. Example: "1567755304968"
Signature	`signature = base64(hmac-sha256(hash_to_sign, hex_decode(api_secret)))` Example: api_secret: “0c3c11e3e74de307866a2d67a9c71f97”

hash_to_sign is the hashed message that must be signed using HMAC-SHA256: hash_to_sign = base64(sha256(string_to_hash))

To build string_to_hash, you must concatenate the following non-empty information:

var parts = [
  "TDXV1",
  api_key,
  nonce,
  timestamp,
  request.method,
  url.host,
  url.path,
  url.query,
  header.content_type,
  request.body
];

// remove empty items (filter)
// add a space separator between each part (join)
string_to_hash = parts.filter(p => p != "").join(" ")

string_to_hash fields
api_key	same as “Authorization”
nonce	same as “Authorization”
timestamp	same as “Authorization”
request.method	the uppercase HTTP verb of the request , namely: “GET“, “POST”, “PUT“, ”DELETE”
url.host	The hostname (lowercase), matching the HTTP "Host" request header field (including any port number). Example: "api.t-dx.com"
url.path	The HTTP request path with leading slash, without trailing slash. Example: "/api/v1/orders"
url.query	Any query parameters or empty string. This should be the exact string sent by the client, including urlencoding. Example: "limit=100&sort=asc"
header.content_type	`Content-Type` header’s value.
request.body	As is.