API Authentication

Overview

The CinCin API uses a signature-based authentication mechanism that requires three custom HTTP headers to be included with every request. This approach ensures that each request is properly authenticated and protected against tampering during transmission.

Required HTTP Headers

All API requests must include the following three headers:

Header	Description
CAP-TOKEN	Your API Key
CAP-NONCE	Current timestamp in milliseconds
CAP-SIGN	SHA-256 signature (see calculation below)

Authentication Process

1

Obtain API Credentials

You need two credentials to authenticate:

• API Key: Your public identifier (sent as CAP-TOKEN)

• Secret Key: Your private signing key (used to generate CAP-SIGN, never sent directly)

2

Generate the Nonce

Create a nonce using the current timestamp in milliseconds:

const nonce = Date.now().toString();

3

Calculate the Signature

The signature calculation differs based on the HTTP method.

For POST requests:

CAP-SIGN = sha256Hex(CAP-NONCE + request_body + query_string + secret)

Components:

• CAP-NONCE: The timestamp in milliseconds

• request_body: The JSON or form-encoded request body as a string

• query_string: The URL query parameters (e.g., param1=value1&param2=value2)

• secret: Your Secret Key

For GET requests:

CAP-SIGN = sha256Hex(CAP-NONCE + query_string + secret)

Components:

• CAP-NONCE: The timestamp in milliseconds

• query_string: The URL query parameters (e.g., param1=value1&param2=value2)

• secret: Your Secret Key

If there are no query parameters, use an empty string for query_string.

Complete Request Examples

POST Request with Query Parameters

POST /cards/v1/transactions?type=withdrawal HTTP/1.1
Host: api.cardinfo.app
Content-Type: application/json
CAP-TOKEN: abc123def456
CAP-NONCE: 1738713600000
CAP-SIGN: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

{"amount": 100, "currency": "USD"}

Signature Calculation:

message = "1738713600000" + '{"amount": 100, "currency": "USD"}' + "type=withdrawal" + secret_key
CAP-SIGN = sha256Hex(message)

GET Request with Query Parameters

GET /cards/v1/list?limit=10&offset=0 HTTP/1.1
Host: api.cardinfo.app
CAP-TOKEN: abc123def456
CAP-NONCE: 1738713600000
CAP-SIGN: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592

Signature Calculation:

message = "1738713600000" + "limit=10&offset=0" + secret_key
CAP-SIGN = sha256Hex(message)