Authentication

Before get started

Please check you have Access Key and Secret Key. If you don't have these keys, please contact Cabital service consultant.

Cabital Connect API uses signature authorization to validate the API request. The process of generating signature authorization is as follows:

1. Add authentication parameters in request header: ACCESS-KEY, ACCESS-TIMESTAMP, ACCESS-NONCE
2. Use the parameters from step 1 to compose the signature string
3. Use Secret Key to encrypt the signature string
4. Use the encrypt result from step 3 as the value of parameter ACCESS-SIGN, and add it to the request header
5. Request APIs with these parameters in the header: ACCESS-KEY, ACCESS-TIMESTAMP, ACCESS-NONCE, ACCESS-SIGN

Be careful

1. DO NOT share the Secret Key, otherwise, it will cause information leakage and unpredictable loss of transaction.
2. If you encounter any problems with authentication, please contact Cabital service consultant and update the Secret Key immediately.

Step 1: Add authentication parameters in request header

Parameter	Description
ACCESS-KEY	Partner's Access Key
ACCESS-TIMESTAMP	Request timestamp, it must be within 30 seconds of the actual time of the request. Otherwise, it will be considered expired and the request will be rejected.
ACCESS-NONCE	The unique value (number or string) in every request. Only the first request will be processed with the same ACCESS-NONCE within 60 minutes.

Step 2: Compose the signature string

StringToSign =
    AccessTimestamp + \n +
    RequestMethod + \n +
    AccessNonce + \n +
    RequestPath + \n +
    RequestBody

Parameter	Description
AccessTimestamp	As same as the header parameter ACCESS-TIMESTAMP
RequestMethod	Request method, should be upper case, e.g: GET, POST, PUT
AccessNonce	As same as the header parameter ACCESS-NONCE
RequestPath	Request path, exclude hostname but include query parameters e.g. /api/v1/accounts/6d92e7b4-715c-4ce3-a028-19f1c8c9fa6c/transfers?direction=CREDIT&has_conversion=true
RequestBody	Request body should be string type if request method is GET should be '' (empty) if request content type is form-data should be '' (empty), e.g. KYC Acceptance

Step 3: Encrypt the signature string

Encrypt the signature string with Secret Key by HMAC-SHA256, and encode the result in Base64 format.

You can validate the encryption result by using this online tool.

Step 4: Add encrypt result in request header

Use the encrypt result from step 3 as the value of parameter ACCESS-SIGN, and add it to the request header. The complete request header parameters as follows:

• ACCESS-KEY
• ACCESS-TIMESTAMP
• ACCESS-NONCE
• ACCESS-SIGN

Examples

Partner's information

• Access Key is b40b978e-ee0c-11ec-8573-0a3898443cb8
• Secret Key is 123 (this is a sample, not a real secret key)

Example 1: GET Request

Take List all transfers by partner's account ID for example.

Parameter	Description
Request URL	GET https://connect.cabital.com/api/v1/userextref/latibac_user_1656053354/transfers?direction=CREDIT&symbol=USDT&created_from=1633445160
Request timestamp	1660017228
Request unique value	1660017228636

1. Compose signature string

   1660017228GET1660017228636/api/v1/userextref/latibac_user_1656053354/transfers?direction=CREDIT&symbol=USDT&created_from=1633445160
   

2. Encrypt the signature string, the result is

   cfa1WY0a5KcVM+NXUDqE1QVBJgO8euOUx59UVhwU6Zs=
   

3. The complete request as follows:

   curl 'https://connect.cabital.com/api/v1/userextref/latibac_user_1656053354/transfers?direction=CREDIT&symbol=USDT&created_from=1633445160' \
      --header 'ACCESS-KEY: b40b978e-ee0c-11ec-8573-0a3898443cb8' \
      --header 'ACCESS-SIGN: cfa1WY0a5KcVM+NXUDqE1QVBJgO8euOUx59UVhwU6Zs=' \
      --header 'ACCESS-TIMESTAMP: 1660017228' \
      --header 'ACCESS-NONCE: 1660017228636'
   

Example 2: PUT Request

Take KYC Match API for example.

Parameter	Description
Request URL	PUT https://connect.cabital.com/api/v1/accounts/bf07fe96-2b05-4281-94ad-4fe39394e707/match
Request timestamp	1660025004
Request unique value	1660025004705

1. Compose signature string

   1660025004PUT1660025004705/api/v1/accounts/bf07fe96-2b05-4281-94ad-4fe39394e707/match{
       "name": "John Doe",
       "id": "880730123",
       "id_document": "PASSPORT",
       "dob": "1985-11-05",
       "issued_by": "TWN"
   }
   

2. Encrypt the signature string, the result is

   dtiC01bc8S/s2IoH1Rq6WrgNIwrKuE4wgxkyP8Cf9+c=
   

3. The complete request as follows:

   curl -X PUT 'https://connect.cabital.com/api/v1/accounts/bf07fe96-2b05-4281-94ad-4fe39394e707/match'
        -d '{
          "name": "John Doe",
          "id": "880730123",
          "id_document": "PASSPORT",
          "dob": "1985-11-05",
          "issued_by": "TWN"
        }'
        --header 'ACCESS-KEY: b40b978e-ee0c-11ec-8573-0a3898443cb8' \
        --header 'ACCESS-SIGN: dtiC01bc8S/s2IoH1Rq6WrgNIwrKuE4wgxkyP8Cf9+c=' \
        --header 'ACCESS-TIMESTAMP: 1660025004' \
        --header 'ACCESS-NONCE: 1660025004705'