> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.tarla.io/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ış

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 toplu olarak, istemci isteklerinin bütünlüğünü, gerçekliğini ve tekrarlanamazlığını ve ayrıca yinelenen gönderimlerin güvenli bir şekilde ele alınmasını sağlar.

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ı** isteyin
</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.

### What if not used?

* İ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 |