> For the complete documentation index, see [llms.txt](https://docs-sdk.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-sdk.crypto-chief.com/processing/go/authentication.md).

# Authentication

How the Crypto Chief Go SDK authenticates and signs every request.

Every request to the Crypto Processing API is authenticated with HTTP headers. **The SDK builds and sets them for you** — you only provide your Merchant ID and API key.

```
Merchant:       <your Merchant ID>
X-CC-Timestamp: <Unix time, seconds>
X-CC-Nonce:     <32 hex, new for every request>
X-CC-Signature: v1=hex(hmacSHA256(API_KEY, stringToSign))
```

## Credentials

Both values come from your dashboard → **Integration** tab:

* **Merchant ID** — identifies your project.
* **API key** — the **signing secret**. It never leaves your server; the SDK uses it to sign requests and to verify incoming webhooks.

{% hint style="warning" %}
Treat the API key like a password. Load it from an environment variable and keep it server-side — never commit it or ship it in client apps.
{% endhint %}

## Initialize the client

```go
c, err := cryptochief.New("MERCHANT_ID", "API_KEY")
if err != nil {
    log.Fatal(err)
}
```

`*Client` is safe for concurrent use — create one and share it across goroutines.

## Configuration options

```go
c, err := cryptochief.New("MERCHANT_ID", "API_KEY",
    cryptochief.WithBaseURL("https://api-processing.crypto-chief.com"), // default
    cryptochief.WithHTTPClient(&http.Client{Timeout: 60 * time.Second}),
    cryptochief.WithRetries(3),                               // retry 5xx + transport errors
    cryptochief.WithRetryBackoff(200*time.Millisecond, 5*time.Second),
    cryptochief.WithUserAgent("my-service/1.0"),
    cryptochief.WithRSAPrivateKey("./rsa_private.pem"),       // optional — wallet decryption
)
```

{% hint style="info" %}
**Test mode** is a per-project toggle in the dashboard, not a separate base URL. Point a test-mode project's credentials at the same client.
{% endhint %}

## How signing works

Every request is signed with HMAC-SHA256 over the request and your API key: `X-CC-Timestamp`, `X-CC-Nonce`, `X-CC-Signature`.

* The timestamp, nonce and signature are computed on every attempt, retries included.
* On `SIGNATURE_TIMESTAMP_OUT_OF_RANGE` the client sets its clock offset from `server_time` and repeats the request once.
* Spaces and tabs at the ends of header values are not part of the HMAC-SHA256 v1 signature: the API removes them before checking `X-CC-Signature`.
* `cryptochief.WithIdempotencyKey(ctx, key)` sends `Idempotency-Key` on the calls made with that context and includes it in the signature.
* `client.Request(ctx, method, path, in, out)` signs a request to a route the SDK has no method for, with any HTTP method.

The string to sign is in the [SDKs overview](/processing/processing.md#authentication).

Webhooks are signed with the same API key: `X-Webhook-Delivery`, `X-CC-Timestamp`, `X-CC-Signature` over the raw body. See [Webhooks](/processing/go/guides/webhooks.md).