Authentication

API Key quickstart

Most of our endpoints will require an API key as a way to authenticate the call. BlockATM provides 3 different types of API :

• Public for non sensitive endpoints, those can be made by your frontend clients. Authentication is performed via a query string parameter.
• Server-to-Server for endpoints that would ideally be called directly from your backend servers. For the Query api, you only need to provide the apikey in request header.
• For creat order Api, you not only need to provide the apikey, but you also need to sign the request data.

Request Limit

• a single API-key cannot be accessed more than 100 times per minute, otherwise 429 will be returned
• If 429 is returned and the access continues, 418 is returned. And subsequent requests will be blocked.

Request Header

Each server to server request needs to contain the following request headers.

request header	Instructions	required
BlockATM-API-Key	You can easily find it at BlockATM console.	true
BlockATM-Request-Time	The timing of your request, down to the millisecond.	false
BlockATM-Signature-V1	Signature using your private key.Only the Create Order API and Create Payout Api requires sign, while the query API only requires providing the API key.	false
BlockATM-Rec_Window	The time window in milliseconds, defaults to 30000 milliseconds if it is null.	false

When the server receives the request, it determines the timestamp in the request, and if it was made before 30000 milliseconds, the request is considered invalid. The time window value can be defined by sending the optional request header BlockATM-RECV_WINDOW.

pseudo-code

 if (requestTime < (serverTime) && (serverTime - requestTime)<= recvWindow)
 {
       // process request
 }
 else
 {
     // reject request
 }

Request signing

You signs the requests that send to blockATM server. The request need includ api-key in each event’s BlockATM-API-Key header. This allows BlockATM to validate that the requests were sent by Your Server, not by a third party.

🚧

It is crucial to emphasize that the private key is securely stored on the your server. This ensures that BlockATM or any other third party cannot tamper with or forge your signature.

Step 1

Generate a pair of public and private keys using EC (Elliptic Curve), store the private key on your server, and store the public key in the backend of BlockAM for the purpose of verifying your requests.

java demo

import java.security.*;

public class ECDSAUtils {
  
  public static KeyPair generateKeyPair() throws NoSuchAlgorithmException {
      KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("EC");
      keyPairGenerator.initialize(256, new SecureRandom());
      return keyPairGenerator.generateKeyPair();   
    }
}

python demo

from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.backends import default_backend

def generate_key_pair():
    private_key = ec.generate_private_key(ec.SECP256R1(), default_backend())
    public_key = private_key.public_key()
    return private_key, public_key

nodejs demo

const crypto = require('crypto');

function generateKeyPair() {
  const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', {
    namedCurve: 'prime256v1',
  });
  return { privateKey, publicKey };
}

Step 2

• For a post request

Concatenate all parameters from the JSON object in ascending order of their keys according to the ASCII character order, using the format "key=value" separated by "&"。Concatenate the 'BlockATM-Request-Time' from the request header in the format '&time=' at the end.

• For a GET request, the search string (e.g., txId=adbb317d-cde9-4ebb-93a3-1b271812de06&custNo=123).

Step 3

Sign the concatenated string using your private key with the SHA256withECDSA algorithm, and pass the resulting signature in the request header.

📘

You can leverage an open-source demo from GitHub to help you with the implementation.