> For the complete documentation index, see [llms.txt](https://docs.cardspro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cardspro.com/getting-started/quickstart.md).

# API Authentication

### Overview <a href="#overview" id="overview"></a>

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 <a href="#required-http-headers" id="required-http-headers"></a>

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 <a href="#authentication-process" id="authentication-process"></a>

#### 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 <a href="#id-2-generate-the-nonce" id="id-2-generate-the-nonce"></a>

Create a nonce using the current timestamp in milliseconds:

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

#### 3. Calculate the Signature <a href="#id-3-calculate-the-signature" id="id-3-calculate-the-signature"></a>

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 <a href="#complete-request-examples" id="complete-request-examples"></a>

#### POST Request with Query Parameters <a href="#post-request-with-query-parameters" id="post-request-with-query-parameters"></a>

```
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 <a href="#get-request-with-query-parameters" id="get-request-with-query-parameters"></a>

```
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)
```