> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.iklim.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API Güvenliği

> Bu sayfa, API istekleri yapmadan önce bilmeniz gereken ayrıntılar hakkında önemli bilgiler sağlar.

# Güvenli API İstek İmzalama ve Idempotency Mekanizması

## Genel Bakış

🧩 Bu API, **HMAC tabanlı istek imzalama, zaman damgası, benzersiz istek tanımlama (nonce)** ve **idempotency anahtarları** içeren sağlam bir güvenlik mekanizmasından yararlanır. Bu mekanizmalar; isteğin bütünlüğünü, kimlik doğrulamasını ve yeniden oynatılamamasını güvence altına alır, aynı zamanda yinelenen gönderimleri güvenle yönetir. 🛡️

📘 Bu belgede her bir mekanizma, amaçları ve gerekli istemci mantığının nasıl uygulanacağı (örneğin Postman veya özel API istemcilerinde) açıklanmaktadır.

## 1. HMAC İmzası (`X-Signature` Başlığı)

### Nedir?

🔑 Bir **HMAC (Karma Tabanlı Mesaj Kimlik Doğrulama Kodu)**, paylaşılan bir sır ve istek verileri kullanılarak oluşturulan bir kriptografik imzadır. Talebin değiştirilememesini ve gönderenin kimliğinin doğrulanabilmesini sağlar.

### Amacı

* **Bütünlük 🛡️:** İsteğin herhangi bir kısmının (yöntem, URI, gövde, zaman damgası) değiştirilip değiştirilmediğini tespit eder.
* **Kimlik Doğrulama 🔐:** İsteğin gizli anahtarı bilen güvenilir bir istemciden geldiğini doğrular.
* **Yeniden Oynatma Önleme ♻️:** Bir zaman damgasına ve benzersiz değerlere bağlı olarak yeniden oynatma saldırılarını tespit edilebilir hale getirir.

### Nasıl Kullanılır?

* İstemci imzalamak için HTTP yöntemini, tam istek yolunu (sorgu dahil), ***milisaniye cinsinden geçerli zaman damgasını*** ve çözümlenmiş istek gövdesini birleştiren bir dize oluşturur 🧾:

```ini theme={null}
dataToSign = HTTP_METHOD + "|" + PATH_WITH_QUERY + "|" + TIMESTAMP + "|" + BODY
```

* İstemci, paylaşılan anahtarı (güvenli bir kasada tutulur, **asla ifşa edilmez**) kullanarak HMAC SHA256 imzasını oluşturur 🔒:

```ini theme={null}
X-Signature = HMAC_SHA256(secret, dataToSign)
```

* Bu imza `X-Signature` istek başlığında gönderilir 🚀.

<Warning>
  ⚠️ İlk API çağrınızı yapmadan önce lütfen bizden **HMAC Anahtarını** talep edin.
</Warning>

### Kullanılmazsa ne olur?

* İstemci http durumu `400 - Hatalı İstek` ile bir hata mesajı alacaktır

```json theme={null}
{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik imza, zaman damgası veya nonce başlıkları",
  "path": "/auth/login"
}
```

### İmza geçerli değilse ne olur?

* İstemci, http durumu `401 - Yetkisiz` olan bir hata mesajı alacaktır.

```json theme={null}
{
  "timestamp": "2025-04-14T16:57:50.083970026",
  "status": 401,
  "error": "Yetkisiz",
  "message": "Geçersiz istek imzası",
  "path": "/auth/login"
}
```

## 2. Zaman Damgası (`X-Timestamp` Başlığı)

### Nedir?

⏱️ İsteğin oluşturulduğu andaki Unix zaman damgası (milisaniye cinsinden).

### Amaç

* **Tekrar Oynatma Önleme 🛑:** Sunucu geçerli istekler için katı zaman pencereleri uygulayabildiğinden, bir saldırganın daha önce geçerli olan bir isteği tekrar kullanmasını önler.

### Nasıl Kullanılır?

* İstemci, isteği göndermeden hemen önce zaman damgasını oluşturur ve bunu `X-Timestamp` başlığı olarak ekler ⌚.

### Kullanılmazsa ne olur?

* İstemci, http durumu `400 - Hatalı İstek` olan bir hata mesajı alacaktır

```json theme={null}
{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik imza, zaman damgası veya nonce başlıkları",
  "path": "/auth/login"
}
```

## 3. Nonce - Tek Seferlik (`X-Nonce` Başlığı)

### Nedir?

🎲 Bir **nonce**, her istekte bulunan rastgele oluşturulmuş benzersiz bir tanımlayıcıdır (UUID v4).

### Amaç

* **Yeniden Oynatma Önleme 🔁:** Her isteği benzersiz bir şekilde tanımlayarak isteğin yeniden oynatılmasını daha da önler. Yöntem, URI ve gövde aynı olsa bile, nonce farklı olacaktır.

### Nasıl Kullanılır?

* İstemci her istek için yeni bir UUID v4 oluşturur ve bunu `X-Nonce` başlığı olarak ekler 🎯.

### Kullanılmazsa ne olur?

* İstemci, http durumu `400 - Hatalı İstek` olan bir hata mesajı alacaktır

```json theme={null}
{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik imza, zaman damgası veya nonce başlıkları",
  "path": "/auth/login"
}
```

### Yeniden kullanılırsa ne olur?

* İstemci http durumu `409 - Çakışma` ile bir hata mesajı alacaktır

```json theme={null}
{
  "timestamp": "2025-04-14T16:57:21.168927321",
  "status": 409,
  "error": "Çakışma",
  "message": "Yeniden oynatma saldırısı tespit edildi (nonce yeniden kullanıldı)",
  "path": "/endpoint/uri/here"
}
```

## 4. Idempotency Anahtarı (`X-Idempotency-Key` Başlığı)

### Nedir?

🪪 Her istek için bir **tekil tanımlayıcı** (UUID v4), sunucunun yinelenen gönderimleri tanımasını ve güvenli bir şekilde göz ardı etmesini sağlar (örneğin, bir POST isteğinin yeniden denenmesi).

### Amaç

* **Idempotency 🔂:** Ağ hataları nedeniyle bir isteğin yeniden denenmesinin yinelenen kaynak oluşturma veya yan etkilere neden olmayacağını garanti eder.

### Nasıl Kullanılır?

* İstemci her işlem için yeni bir UUID v4 oluşturur ve bunu `X-Idempotency-Key` başlığı olarak gönderir 📮.

### Kullanılmazsa ne olur?

* İstemci, http durumu `400 - Hatalı İstek` olan bir hata mesajı alacaktır

```json theme={null}
{
  "timestamp": "2025-04-14T16:26:54.203118461",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik X-Idempotency-Key başlığı",
  "path": "/endpoint/uri/here"
}
```

### Yeniden kullanılırsa ne olur?

* İstemci http durumu `409 - Çakışma` ile bir hata mesajı alacaktır

```json theme={null}
{
  "timestamp": "2025-04-14T16:56:28.671809875",
  "status": 409,
  "error": "Çakışma",
  "message": "Yinelenen istek algılandı (X-Idempotency-Key)",
  "path": "/endpoint/uri/here"
}
```

<Card title="Güvenlikle İlgili Hususlar" icon="shield-halved">
  * HMAC için kullanılan `anahtar` **istemci kodunda veya belgelerinde asla paylaşılmamalı veya ifşa edilmemelidir** 🔐.
  * Ortadaki adam saldırılarını önlemek için her zaman HTTPS kullanın 🌐.
  * Sunucular, `X-Timestamp` için izin verilen maksimum bir zaman eğriliği uygular ve belirli bir pencere içinde kullanılmış/tekrarlanmış `X-Nonce` veya `X-Idempotency-Key` değerlerini reddeder ⛔.
</Card>

<Card title="Örnek Başlıklar" icon="table-list">
  ```ini theme={null}
  X-Signature: 75c759570bbb5dfd40136cffd3dbaa51b28d4620e51359161686790adcc53bea
  X-Timestamp: 1752751106704
  X-Nonce: 684a0dca-bd6a-4056-a449-2567f9847f9c
  X-Idempotency-Key: 777edc03-ad49-4c17-be6b-9baf05a1b9e0
  ```
</Card>

### Özet Tablo 📊

<Icon icon="table-cells" size={32} />

| Başlık            | Değer/Format             | Amaç                               |
| ----------------- | ------------------------ | ---------------------------------- |
| X-Signature       | Hexadecimal string       | Orijinallik/bütünlük talebi        |
| X-Timestamp       | Milliseconds since epoch | Yeniden oynatmayı önler            |
| X-Nonce           | UUID v4                  | Teklik/tekrarı önleme              |
| X-Idempotency-Key | UUID v4                  | Yeniden denemeler için Idempotency |