API Authentication

This document describes the authentication mechanism for the CardsPro API using custom HTTP headers with SHA-256-based signatures.

Overview

The CardsPro API uses a signature-based authentication system that requires three custom HTTP headers on every request. This ensures that requests are authenticated and have not been tampered with in transit.

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

Note: 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.cardspro.com
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.cardspro.com
CAP-TOKEN: abc123def456
CAP-NONCE: 1738713600000
CAP-SIGN: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592

Signature Calculation:

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