> For the complete documentation index, see [llms.txt](https://kreatorverse-2.gitbook.io/kollect-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kreatorverse-2.gitbook.io/kollect-documentation/security.md).

# Security

Server-to-server calls to `POST /sdk/server/create-payment` use **three coordinated mechanisms**:

1. **API key and secret** — identifies the merchant and loads access-token verification.
2. **HMAC request signature** — proves possession of the secret and binds the request to method, path, time, and body.
3. **Idempotency key** — prevents accidental duplicate payments when clients retry.

All three are **mandatory** for the create-payment endpoint.

***

## API key and secret

### Where to send credentials

| Credential | Header                                                        |
| ---------- | ------------------------------------------------------------- |
| API key    | `Authorization: Bearer <apiKey>` **or** `X-API-Key: <apiKey>` |
| Secret     | `X-Secret-Key: <secretKey>`                                   |

The server looks up an **access token** record matching **both** `apiKey` and `secretKey`. The record must be **active**; otherwise the API returns `403` or `401` depending on the case.

### Merchant context

After successful authentication, downstream code receives:

* MerchantId (merchant identity)
* Per-merchant **rate limit** budget (numeric `limit` on the token, used by the per-key limiter)

***

## Signature headers (required after auth)

Signing is enforced by dedicated middleware. In addition to credentials, you **must** send:

| Header        | Purpose                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `X-API-Key`   | Must equal the authenticated API key (signing requires this header explicitly).                                       |
| `X-Timestamp` | Unix seconds; must fall within a **±300 second** window of server time.                                               |
| `X-Signature` | HMAC-SHA256 of the canonical base string (see [Request signing](/kollect-documentation/security/request-signing.md)). |

***

## Failure modes (authentication)

| Symptom                           | Typical cause                                               |
| --------------------------------- | ----------------------------------------------------------- |
| `401` + `INVALID_API_KEY`         | Missing header, wrong key/secret pair, or inactive token.   |
| `401` + message about `X-API-Key` | API key header missing or does not match authenticated key. |

Repeated failed authentication attempts may be **rate limited** separately; see [Rate limits](/kollect-documentation/reference/rate-limits.md).

***

## Related pages

* [Request signing (HMAC)](/kollect-documentation/security/request-signing.md)
* [Idempotency](/kollect-documentation/security/idempotency.md)
* [Create payment URL](/kollect-documentation/api-reference/create-payment.md)