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

# API Anahtarı Yönetimi

> Server-to-server entegrasyonlar için OAuth 2.0 Client Credentials çiftleri.

Payven'de "API anahtarı", **OAuth 2.0 Client Credentials çiftidir**. Bir API anahtarı oluşturduğunuzda Identity arka tarafta yeni bir OAuth client kaydeder ve size `client_id` + `client_secret` çifti verir. Bu çift ile [`POST /auth/{slug}/token`](/documentation/concepts/authentication) endpoint'inden access token alır, ürün servislerine `Authorization: Bearer ...` ile çağrı yaparsınız.

<Note>
  **Uzun ömürlü vs kısa ömürlü:** `client_id` + `client_secret` çifti **uzun ömürlü** kimlik bilgisidir; API çağrılarında doğrudan kullanılmaz. Bunlarla **kısa ömürlü access token** üretilir; istek başına gönderilen Bearer token budur. Tek başına `client_id` ile API çağrısı yapamazsınız.
</Note>

## Anahtar yapısı

| Bileşen         | Açıklama                                                        | Örnek               |
| --------------- | --------------------------------------------------------------- | ------------------- |
| `client_id`     | Public tanımlayıcı (OAuth client ID)                            | `pvk-payven-a1b2c3` |
| `client_secret` | Gizli — yalnızca oluşturma + rotasyon anında bir kez gösterilir | `whsec_AbC...XyZ`   |

Client ID prefix'i `pvk-{tenant-slug}-{rastgele}` formatındadır. Sandbox/production ayrımı **tenant slug'ı** üzerinden yapılır (sandbox tenant'ı için ayrı slug + ayrı API key).

## Endpoint'ler

Bearer access token gerektirir (kullanıcı `tenant-admin` rolünde olmalı).

```http theme={null}
GET    /api/v1/tenants/me/api-keys                    # Liste (sayfalı)
GET    /api/v1/tenants/me/api-keys/{id}               # Tek anahtar
POST   /api/v1/tenants/me/api-keys                    # Yeni anahtar
PUT    /api/v1/tenants/me/api-keys/{id}               # Güncelleme
DELETE /api/v1/tenants/me/api-keys/{id}               # Silme (revoke)
POST   /api/v1/tenants/me/api-keys/{id}/rotate-secret # Secret rotasyonu
```

## Liste

```bash theme={null}
curl https://identity.payven.com.tr/api/v1/tenants/me/api-keys \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
```

Yanıt — sayfalı `ApiKeyDto` listesi:

```json theme={null}
{
  "items": [
    {
      "id":                       "8e3f5c12-...",
      "tenant_id":                "1a2b3c4d-...",
      "client_id":       "pvk-payven-a1b2c3",
      "display_name":             "Production — Ödeme Servisi",
      "contact_email":            "ops@example.com",
      "merchant_id":              "M-IST-001",
      "plan_id":                  "abc-...",
      "plan_code":                "standard",
      "plan_name":                "Standart Plan",
      "daily_limit_override":     null,
      "monthly_limit_override":   null,
      "rate_limit_override":      null,
      "effective_daily_limit":    100000,
      "effective_monthly_limit":  3000000,
      "effective_rate_limit":     200,
      "allowed_ips":              "52.18.42.10,52.18.42.0/24",
      "expires_at":               null,
      "is_active":                true,
      "created":                  "2026-01-15T10:00:00.000+00:00"
    }
  ],
  "page":              1,
  "total_pages":       1,
  "total_count":       4,
  "has_previous_page": false,
  "has_next_page":     false
}
```

| Alan           | Açıklama                                                                           |
| -------------- | ---------------------------------------------------------------------------------- |
| `client_id`    | OAuth Client Credentials akışında `client_id` olarak kullanılan public tanımlayıcı |
| `display_name` | İnsan-okur ad (raporlama için)                                                     |
| `merchant_id`  | Bu anahtarın "default merchant"ı — access token claim'ine yansır                   |
| `plan_*`       | Atanmış plan (rate limit + günlük/aylık limit kaynağı)                             |
| `*_override`   | Plan default'unu override eden tenant-spesifik limit                               |
| `effective_*`  | Override'lar uygulanmış nihai limit (access token claim'ine basılır)               |
| `allowed_ips`  | CSV IP / CIDR listesi                                                              |
| `expires_at`   | Anahtarın otomatik pasifleşeceği tarih (boş = sınırsız)                            |
| `is_active`    | Pasif anahtarlar token üretemez                                                    |

<Note>
  **`client_secret` listede her zaman gizli.** Sadece oluşturma + rotasyon yanıtında bir kez döner.
</Note>

## Yaşam döngüsü

```mermaid theme={null}
flowchart LR
    A[POST .../api-keys] --> B[Aktif]
    B -->|POST .../rotate-secret| B
    B -->|PUT .../api-keys/id<br/>is_active=false| C[Pasif]
    C -->|PUT .../api-keys/id<br/>is_active=true| B
    B -->|DELETE| D[Silinmiş]
    C -->|DELETE| D
```

## En iyi uygulamalar

<Check>**Ortam başına ayrı anahtar** — sandbox tenant'ı için ayrı `client_id` üret, production'la karıştırma.</Check>
<Check>**Servis başına ayrı anahtar** — sızıntı durumunda etki alanı sınırlı kalır, audit kolaylaşır.</Check>
<Check>**Production için IP whitelist zorunlu** — `allowed_ips` doldurmadan production anahtar dağıtmayın.</Check>
<Check>**6 ayda bir rotasyon** — `rotate-secret` ile secret'ı yenileyin (eski 24 saat geçerli kalır, zero-downtime geçiş).</Check>
<Check>**Ekipten ayrılma protokolü** — bir kişi ayrıldığında o kişinin erişebildiği anahtarları rotasyona alın.</Check>

Detay: [API Anahtarı En İyi Uygulamaları](/documentation/security/api-key-best-practices).

## Sıradaki adımlar

<CardGroup cols={2}>
  <Card title="Yeni anahtar oluştur" icon="plus" href="/identity/api-keys/create">
    Adım adım kayıt + secret saklama.
  </Card>

  <Card title="Secret rotasyonu" icon="arrows-rotate" href="/identity/api-keys/rotate">
    Sızıntı şüphesi veya zamanlı rotation.
  </Card>

  <Card title="Anahtar revoke" icon="trash" href="/identity/api-keys/revoke">
    Pasif/sil — kullanılmayan anahtarları temizle.
  </Card>

  <Card title="Token alma akışı" icon="key" href="/documentation/concepts/authentication">
    Aldığınız client\_id+secret ile token nasıl alınır?
  </Card>
</CardGroup>