API anahtarlari, makine-makine kimlik dogrulamasinin en yaygın ve en cok kotuye kullanilan yontemlerinden biridir. Basit entegrasyon saglarlar; ancak duz metin olarak repoda birakildiklarinda, log'lara yazildiklarinda veya rotasyonsuz yillarca kullanildiklarinda ciddi güvenlik olaylarina yol acarlar. API key yönetimi; anahtar yaşam dongusunun — üretim, dagitim, kullanım, rotasyon, iptal — sistematik ve denetlenebilir şekilde tasarlanmasini gerektirir.
API key vs OAuth vs mTLS
API key, paylasilan bir sır degeridir; bilen herkes yetkilidir. OAuth client credentials veya JWT service token kisa omurlu ve scope sinirli olabilir; mTLS ise sertifika tabanli güçlü kimlik sağlar. API key uygun senaryolar: public read-only API, webhook dogrulama, geliştirici sandbox, düşük riskli entegrasyonlar. Yüksek degerli işlemler icin API key tek basina yeterli degildir; IP allowlist, rate limit ve scope ile guclendirilmelidir.
Anahtar uretimi
Güvenli rastgele üretim icin kriptografik RNG kullanın; UUID veya tahmin edilebilir sequential ID kullanmayin. Anahtar yeterli entropiye sahip olmali (en az 128 bit, pratikte 256 bit). Prefix ile anahtar tipi ayirt edilebilir: sk_live_, sk_test_, whsec_. Prefix, anahtarin log veya ekran goruntusunde yanlislikla kullanilmasini azaltir; gerçek secret suffix yalnizca bir kez gosterilir.
// Ornek format (Stripe benzeri)
sk_live_51Hq... → uretim secret key
pk_live_... → publishable (client-safe) key
whsec_... → webhook signing secret
Saklama ve hash
API key veritabanında duz metin saklanmamalıdır. Kayıt sirasinda SHA-256 veya bcrypt ile hash'lenir; dogrulama gelen key hash karsilastirmasi ile yapilir. Salt kullanımı rainbow table saldirisini onler. Lookup icin key'in son 4 karakteri veya fingerprint açık saklanabilir; destek ekibi hangi key oldugunu tanir ama key'i geri uretemez.
- Client tarafı: Environment variable veya secret manager; asla kaynak kodda.
- Sunucu tarafı: Hash + metadata (owner, scope, created, last_used).
- CI/CD: Platform secret store; OIDC ile enjekte.
Scope ve kapsam sinirlandirmasi
Her API key'e minimal scope atanir: read:products, write:orders. Monolithic full-access key anti-pattern'dir. Scope matrisi RBAC yetki matrisi ile ayni disiplini takip eder. Tenant bazli key'ler yalnizca ilgili tenant verisine erisir; cross-tenant sızıntı API gateway'de tenant header ve key metadata eslestirmesi ile onlenir.
Rotasyon ve iptal
Rotasyon dual-key donemi ile yapilir: yeni key oluşturulur, tuketiciler güncellenir, eski key grace period sonunda iptal edilir. Otomatik rotasyon 90 gunluk periyot ile planlanir; manual rotasyon compromise suphesinde aninda. Iptal edilen key'in cache'de yasamasi icin revocation list TTL tanimlanir. Webhook secret rotasyonunda hem eski hem yeni imza geçici olarak kabul edilebilir.
Last-used izleme
Her başarılı dogrulamada last_used_at ve last_used_ip güncellenir. 90 gun kullanılmayan key otomatik deaktive edilir (orphan key temizligi). Ani IP veya ulke degisimi anomaly detection tetikler.
Rate limiting ve abuse onleme
API key basina rate limit (token bucket veya sliding window) uygulanir. Asiri istek 429 doner; tekrarlayan abuse key suspend edilir. Global ve key-bazli limit katmanları birlikte çalışır. DDoS senaryosunda gateway seviyesinde ek koruma devreye girer.
Webhook imza dogrulama
Gelen webhook'larda API key yerine HMAC imza kullanılır. Paylasilan secret ile payload imzalanir; alici timing-safe comparison ile dogrular:
var expected = HMACSHA256(webhookSecret, requestBody);
if (!CryptographicOperations.FixedTimeEquals(expected, receivedSignature))
return Unauthorized();
Replay saldirisina karşı timestamp tolerance (5 dakika) ve nonce veya event ID deduplication uygulanir.
Developer experience ve güvenlik dengesi
Developer portal self-service key oluşturma sunar; ancak onay workflow ve scope seçimi sinirli kalir. Test ve production key'leri ayri namespace'te; test key production endpoint'e erisemez. Key oluşturma audit log'a duser; Slack bildirimi opsiyonel. Dokumantasyonda key güvenliği best practice'leri açıkça belirtilir.
Incident response
Key compromise playbook: tüm etkilenen key'leri aninda iptal, yeni key uret ve dagit, erişim loglarini incele, etkilenen veriyi belirle, yasal bildirim gereksinimini değerlendir. Git history'de key tespit edildiyse history temizligi yetmez — rotate sart. Secret scanning (gitleaks, GitHub Advanced Security) pre-commit ve CI'da çalışır.
Alternatif mimariler
Olgun platformlarda API key yerine kisa omurlu OAuth token veya workload identity tercih edilir. API key legacy entegrasyonlar icin korunur; yeni entegrasyonlar modern auth'a yonlendirilir. Mutual TLS kurumsal B2B senaryolarda güçlü alternatiftir; sertifika yönetimi maliyeti vardir.
Metrikler
- Aktif key sayisi ve ortalama omur
- Rotasyon SLA uyumu (yüzde)
- Suspend edilen key / abuse orani
- Orphan key (kullanılmayan) temizlik sayisi
API key yönetimi, basit gorunen bir mekanizmayi olgun bir güvenlik programina donusturur. Güvenli üretim, hash'le saklama, minimal scope, rotasyon, rate limit ve izleme bir arada uygulandiginda API key makul risk profili ile kullanılabilir; aksi halde en zayif halka olmaya devam eder. Platform olgunlugu arttikca API key yerine kisa omurlu token ve workload identity gecisi planlanmalidir.
Multi-region ve replikasyon
Global API'de key dogrulama tüm bolgelerde tutarlı olmali; merkezi key store veya eventual consistent replication tercih edilir. Revocation event'i tüm edge node'lara push edilir; stale cache penceresi kabul edilebilir ust sınır dokumante edilir. Bolgesel outage'da read-only fallback key validation local replica'dan yapilabilir; write islemleri merkezi iptal listesine bağlı kalir.
Key metadata ve sahiplik
Her key'e owner team, ticket referansi, açıklama ve environment etiketi zorunludur. Sahipsiz key periyodik temizlik job'i ile silinir. Offboarding workflow çalışan ayrildiginda kişisel key'leri otomatik iptal eder. Shared team key yerine servis hesabi key tercih edilir; sorumluluk servis catalog kaydina baglanir.
Gateway ve API management katmanı
API gateway (Kong, AWS API Gateway, Azure APIM) key dogrulamayi merkezi yapar; backend servisler key bilmez. Gateway key metadata'dan scope ve rate limit uygular; backend'e dahili identity header iletir. Bu ayrim backend kodunu sadelestirir ve key rotation'u tek noktadan yönetilebilir kilar. Gateway log'larinda key degeri degil key ID loglanir; PII ve secret sızıntisi onlenir.
B2B entegrasyon güvenliği
Kurumsal musterilere verilen API key'ler sözleşme kapsamindaki endpoint ile sinirli olmalidir. IP allowlist ve mutual TLS ek katman olarak eklenebilir. Partner onboarding'de key yalnizca güvenli kanal (encrypted email, portal one-time display) ile iletilir. Partner offboarding'de key aninda iptal ve erişim loglari paylasilir. SLA ihlali veya abuse durumunda suspend proseduru onceden tanimlanir.
Gozlemlenebilirlik
API key kullanım metrikleri: istek hacmi, hata orani, latency dagilimi, benzersiz endpoint kullanımı. Anomaly detection ani trafik artisi veya yeni ulke kaynagini flagler. Dashboard'da key bazli kullanım gorunurlugu destek ve güvenlik ekiplerine ortak dil sağlar. Metrikler GDPR/KVKK kapsamında kişisel veri icermemeli; yalnizca teknik telemetry tutulur.
Key lifecycle otomasyonu
Tüm lifecycle adimlari API veya IaC ile otomatize edilmelidir: oluşturma onay workflow, otomatik expiry uyarisi, grace period sonrasi iptal. Manuel adim sayisi azaldikca operasyonel hata ve sızıntı riski duser. Terraform veya Pulumi ile key metadata ve scope tanimi kod olarak versiyonlanir; drift tespit edilir. Otomasyon olgunlugu olculurken manuel key oluşturma oraninin sifira yaklasmasi hedeflenir.
