API Anahtarı Yönetimi

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 endpoint’inden access token alır, ürün servislerine Authorization: Bearer ... ile çağrı yaparsınız.

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.

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ı).

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

curl https://identity.payven.com.tr/api/v1/tenants/me/api-keys \
  -H "Authorization: Bearer $PAYVEN_TOKEN"

Yanıt — sayfalı ApiKeyDto listesi:

{
  "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

client_secret listede her zaman gizli. Sadece oluşturma + rotasyon yanıtında bir kez döner.

Yaşam döngüsü

En iyi uygulamalar

Ortam başına ayrı anahtar — sandbox tenant’ı için ayrı client_id üret, production’la karıştırma.

Servis başına ayrı anahtar — sızıntı durumunda etki alanı sınırlı kalır, audit kolaylaşır.

Production için IP whitelist zorunlu — allowed_ips doldurmadan production anahtar dağıtmayın.

6 ayda bir rotasyon — rotate-secret ile secret’ı yenileyin (eski 24 saat geçerli kalır, zero-downtime geçiş).

Ekipten ayrılma protokolü — bir kişi ayrıldığında o kişinin erişebildiği anahtarları rotasyona alın.

Detay: API Anahtarı En İyi Uygulamaları.

Sıradaki adımlar

Yeni anahtar oluştur

Adım adım kayıt + secret saklama.

Secret rotasyonu

Sızıntı şüphesi veya zamanlı rotation.

Anahtar revoke

Pasif/sil — kullanılmayan anahtarları temizle.

Token alma akışı

Aldığınız client_id+secret ile token nasıl alınır?

Genel Bakış

Oturum Bilgisi

Lookup Servisleri

Doğrulama

API Anahtarı Yönetimi

Anahtar yapısı

Endpoint’ler

Liste

Yaşam döngüsü

En iyi uygulamalar

Sıradaki adımlar

Yeni anahtar oluştur

Secret rotasyonu

Anahtar revoke

Token alma akışı

​Anahtar yapısı

​Endpoint’ler

​Liste

​Yaşam döngüsü

​En iyi uygulamalar

​Sıradaki adımlar

Yeni anahtar oluştur

Secret rotasyonu

Anahtar revoke

Token alma akışı

Anahtar yapısı

Endpoint’ler

Liste

Yaşam döngüsü

En iyi uygulamalar

Sıradaki adımlar