Bunu yaşayan biri olarak söyleyeyim, SaaS ürünlerinde API anahtarı işi, dışarıdan bakınca ufak bir ayrıntı gibi duruyor. Ama işin içine entegrasyon, otomasyon, CI/CD ve üçüncü parti uygulamalar girince, o “küçük detay” bir anda sistemin omurgasına dönüşüyor. Geçen yıl Şubat 2025’te, İstanbul’daki bir startup ekibiyle yaptığım kısa danışmanlıkta tam da bunu gördüm: OAuth isteyen kullanıcı ayrıydı, “bana sadece key ver yeter” diyen geliştirici ayrıydı — dürüst olayım, biraz hayal kırıklığı —. İkisini aynı kapıya sıkıştırmaya çalışınca ortalık biraz karıştı. Ciddi karıştı.
Dürüst olmak gerekirse, İşin aslı şu ki; herkes tarayıcıdan giriş yapmak istemiyor. Bazı ekipler script ile bağlanmak istiyor, bazıları GitHub Actions içinde çağrı atıyor, bazıları da kendi iç araçlarını beslemek için sade bir anahtar arıyor. Burada düzgün tasarlanmış bir API key sistemi bir düşüneyim… devreye giriyor. Hem rahatlık veriyor hem de güvenlikten ödün vermeden ilerlemenizi sağlıyor — tabii doğru kurarsanız. Peki neden? Çünkü kullanım şekli değişince beklenti de değişiyor.
Neden API Anahtarı Meselesi Hala Önemli?
OAuth çok konusuluyor, evet. Ama her kullanim senaryosu OAuth’a uymuyor. Bir SaaS ürünü — kendi adıma konuşayım — düşünün; müşteri paneline girmek isteyen son kullanıcı var, bir de bu ürünü kendi altyapısına bağlamak isteyen geliştirici var. Bu ikinci grup için çoğu zaman en pratik çözüm API anahtarı oluyor (inanın bana). Hızlı başlatılıyor, otomasyona uyuyor ve insan müdahalesini azaltıyor. Kısacası iş görüyor.
Bir dakika — bununla bitmedi.
Benzer tabloyu 2024 sonbaharında Ankara’da bir B2B yazılım firmasında da gördüm. Ekip önce sadece oturum bazlı erişimle gitmişti ama birkaç hafta sonra müşterilerden biri “biz bunu Jenkins’ten çağıracağız” deyince ihtiyaç değişti. Yani mesele sadece teknik değil; ürün stratejisi meselesi de bu. Kullanıcıya seçenek sunmazsanız bazen güzelim özellik rafta kalıyor. Sonra kimse niye kullanılmadığını anlayamıyor.
Gel gelelim iş burada bitmiyor. API key verirken “nasıl olsa iç sistem” diye gevşerseniz sonra log sızıntısı, yanlış yetki veya revokeyi unutulan anahtarlar yüzünden başınız ağrıyabilir. Kağıt üstünde basit görünen şey pratikte baya dikkat istiyor. Siz hiç denediniz mi? Açık konuşayım, ihmal edilince ilk patlayan yerlerden biri burası oluyor.
API anahtarını şifre gibi değil, geçici ama sağlam bir kimlik kartı gibi düşünün: Kullanıcıya gösterirsiniz ama sistem içinde düz metin olarak saklamazsınız.
Veri Modeli Nasıl Kurgulanmali?
Şöyle söyleyeyim, Iyi bir veri modeli kurmadan işe başlamayın derim (ciddiyim). Çünkü sonra alan eklemek zorlaşıyor, migration peşinden koşuyorsunuz… biliyorum, can sıkıcı tarafı bu. Ben ilk kez böyle bir model tasarlarken 2023’te küçük bir SaaS projesinde sadece key alanıyla başlamıştım; iki ay sonra iptal edilen anahtarları takip etmek isteyince model yetersiz kaldı. Tabloyu yeniden düzenlemek zorunda kaldık. O gün baya uğraştırmıştı.
Ve işler burada ilginçleşiyor.
Daha sağlam yaklaşımda her anahtarın sahibi belli olur, adı olur, hash’i olur ve mümkünse prefix’i olur. Prefix kısmı özellikle kullanışlıdır çünkü kullanıcı panelinde neredeyse tüm anahtarı açığa çıkarmadan tanımlama yaparsınız. Mesela “sk_live_ab12cd34” gibi yarım görünüm hem destek ekibine yardımcı olur hem de tam değeri saklamaz. E peki, sonuç ne oldu? Basit ama işe yarayan kısım bu. Daha fazla bilgi için C++ Neden Hâlâ Ayakta? Stroustrup’tan Gelen Dersler yazımıza bakabilirsiniz.
| Alan | Ne IsE Yarar? | Neden Önemli? |
|---|---|---|
| userId | Anahtarın sahibini belirtir | Kime ait olduğunu bilmek için |
| name | Anahtara açıklayıcı isim verir | “Production”, “CI/CD” gibi ayrım için |
| keyHash | Düz metin yerine hash saklar | Sızıntıda gerçek anahtarı korur |
| keyPrefix | Kısmi görünürlük sağlar | Kullanıcı dostu yönetim için |
| revokedAt / expiresAt | Pasifleşme ve süre takibi yapar | Tam kontrol sağlar |
Neyi saklayip neyi saklamayacaginizi bilin
Bi saniye — Burası kritik nokta: raw key’i veritabanında tutmayın. Tahmin eder misiniz? Nokta.
Sadece hash tutun ve kullanıcıya o ham değeri yalnızca bir kez gösterin.
Bu yaklaşım kulağa sert geliyor olabilir ama güvenlik tarafında en temiz yol bu.
Evet.
Anahtar Uretimi: Guclu Başlangıç Nasıl Yapılır?
Anahtar üretirken tahmin edilebilir şeylerden kaçınmak gerekiyor.
Tarih damgası koyup üstüne biraz rastgele sayı eklemek eski usul kalır; saldırganlar böyle desenleri seviyor çünkü analiz etmesi kolay oluyor.
Bunun yerine kriptografik olarak güvenli rastgelelik kullanmak şart.
Peki neden? Çünkü desen bırakmayan yapı daha az sürpriz çıkarıyor (ben de ilk duyduğumda şaşırmıştım)
Bir saldırgan milyonlarca deneme yapabilse bile desen yakalayamamalı.
Bu yüzden rastgele bayt üretimi temel taş sayılır.
// Basitleştirilmiş örnek
import crypto from 'crypto';
import bcrypt from 'bcryptjs';
function generateApiKey() {
const rawKey = `sk_live_${crypto.randomBytes(32).toString('hex')}`;
const prefix = rawKey.slice(0, 16);
const hash = bcrypt.hashSync(rawKey, 12);
return {
raw: rawKey,
hash,
prefix
};
}Bence burada en mantıklı denge şu: üretimde güçlü random kullanın ama kullanıcı deneyimini de unutmayın.
Prefix sayesinde destek ekibi hangi anahtardan söz edildiğini anlayabiliyor; tam değer ise tek seferlik gösteriliyor.
Bu fena değil, hatta baya iş görüyor.
E tabi küçük startup ile enterprise arasında fark var burada da ortaya çıkıyor. Daha fazla bilgi için Bjarne Stroustrup ve C++: Eski Dilin Yeni Hali yazımıza bakabilirsiniz.
Küçük ekipte basit. Temiz çözüm yeterli olabilir; büyük yapılarda ise audit log, rotation politikası ve bölgesel erişim sınırı gibi şeyler hemen gündeme gelir.
Neyse uzatmayalım.
Bazen mesele koddan çok operasyon oluyor (en azından benim deneyimim böyle)
Create Endpoint Yazarken Nelere Dikkat Ettim?
Editör masasında bu konuyu ilk not aldığımda aklıma hemen şu geldi: “Aslında en zor kısım üretmek değil, kontrol etmek.” Çünkü endpoint tarafında session doğrulaması yapmazsanız açık kapı bırakmış olursunuz.
Yetkisiz istekleri kesmek şart.
Kod temiz görünse bile güvenlik boşluğu varsa olay orada biter. dissectml: EDA ile AutoML Arasındaki Eksik Parça yazımızda bu konuya da değinmiştik.
Kendi testlerimde Mart 2025’te Next.js App Router kullanan küçük bir proje üzerinde şunu gördüm: route handler içinde doğrulama net olunca kod sadeleşiyor. Limit koymayı unutursanız kullanıcı saçma sapan şekilde yüzlerce key üretebiliyor (evet oldu).
O yüzden maksimum aktif key sayısı koymak gayet mantıklı.
Ayrıca böyle durumlarda log da hayat kurtarıyor.
- Kullanıcı oturumunu doğrula.
- Anahtar adı boş mu kontrol et.
- Aynı kullanıcı için aktif key sayısını sınırla.
- Sadece hash’i kaydet.
- Düz metni yalnızca response içinde döndür.
Buna benzer limitler başlangıçta fazla temkinli gelebilir ama pratikte hayat kurtarıyor.
Neyse uzatmayayım; beş adet aktif key sınırı çoğu SaaS için makul başlangıç noktasıdır.
Tabii çok büyük platformlarda bu sayı değişebilir — müşterinin rolüne göre bile farklılaştırabilirsiniz.
Siz ne dersiniz?
Doğrulama Tarafı Asıl Güvenlik Duvari
Anahtarı üretmek kolay taraf gibi duruyor… esas iş doğrulamada başlıyor.
Bir istek geldiğinde düz metin karşılaştırması yapmak yerine hash üzerinden eşleştirme yapmanız gerekir.
Aksi halde veritabanınız sızarsa olay tatsızlaşır.
Burada bcrypt gibi algoritmalar iş görüyor çünkü tek yönlü yapı sunuyor ve brute force maliyetini artırıyor.
Ben bunu ilk kez canlı ortamda Ekim \(2024\) tarihinde İzmir’deki orta ölçekli bir e-ticaret projesinde gözlemledim:
bir test ortamında yanlışlıkla log’a düşen header yüzünden ekip paniğe kapıldı.
Ama hash sakladıkları için hasar sınırlı kaldı.
Açık konuşayım,
bu tarz günlerde insan biraz kahvesine sarılıyor… OpenAI’dan Güvenlik İçin Yeni Hamle: Fellowship Programı Ne Anlatıyor? yazımızda da bu konuya değinmiştik. AI Ajanlar Neden Yalan Söyler: Asıl Ders Ne? yazımızda da bu konuya değinmiştik.
Sadece eslestirme yetmez, durum takibi de lazım”
“lastUsedAt” alanını hafife almayın.
Bu alan size hangi entegrasyonun hala yaşadığını gösterir.
Üstelik kullanılmayan anahtarları temizlemek daha kolay olur.
Bir ay boyunca dokunulmayan key varsa onu incelemek iyi fikir olabilir.
Tam otomatik silme yerine önce uyarı göndermek genelde daha güvenlidir.”
Evet.
Küçük Startup ile Kurumsal Yapı Arasinda Fark Nerede?
Size bir şey söyleyeyim, Küçük startup’ta hedef genelde hızlı teslimattır.
Tek takım vardır ya da iki takım vardır;
sistem karmaşıklığı düşük tutulur,
dokümantasyon hafif olur,
panelde birkaç buton yeterli.
Burada önemli olan şey işleri gereksiz yere ağırlaştırmamak.
Mesela ben geçen Haziran ayında Kadıköy’de çalışan üç kişilik bir ekipte bunu gördüm:
önce basit create/revoke akışı kurdular,
sorunsuz çalıştı,
yeterince iyi oldu.
“Kurumsal tarafta ise hikaye değişiyor.”
abartmıyorum;
auditing,
geographic restrictions,
detailed logs,
okuma-yazma yetkileri,
kullanıcı gruplarına göre scope ayrımı…
bunların hepsi masaya geliyor.” Bir de şu var:
eğer müşteri kendi compliance dünyasında yaşıyorsa sizin API key sistemi ona uyumlu olmak zorunda.”
Yani teknik çözüm kadar yönetişim de önemli.”
“Avantajlar” kadar “eksiler” de konussun”
“API keys hızlıdır.”
bu tamam.
ama dezavantaj da açık:
kullanıcı cihaz değiştirdiğinde ya da employee offboarding olduğunda iptal sürecini düzgün yönetmezseniz risk büyür.”
hatta bazen OAuth’a kıyasla daha kaba görünür çünkü granular izin modeli zayıf kalabilir.”
burada dürüst olmak lazım;
hangi senaryoda neyin uygun olduğunu söylemek ürün ekibinin işi.”
“Pratik Bir Kontrol Listesi” ile Toparlayalim”
“Bakın şimdi,”
basit görünen sistemlerin altında genelde çok fazla köşe bulunur.”
başlangıçta aşağıdaki listeyi uygularsanız hataların yarısını daha doğmadan kesersiniz:
- Tam değeri asla DB’ye yazma;\User panelinde yalnızca prefix göster;\Aktif key sayısını sınırla;\Zorunlu revoke mekanizması ekle;\Kullanımı logla;\Süre dolumu desteği koy;
- Error mesajlarını fazla konuşkan yapma.”
\
“Güzel görünen ama izlenmeyen API anahtarı sistemi aslında eksik sistemdir.” Bunu bizzat birkaç projede yaşadım; revocation vardı ama kullanım analitiği yoktu ve sorun haftalar sonra fark edildi.”
\
Sıkça Sorulan Sorular”
\
“API anahtarı ile OAuth arasındaki fark nedir?”
out”
p>”API anahtarı daha sade ve makineden makineye erişimde pratiktir.” OAuth ise kullanıcı onayı ve kapsam yönetimi açısından daha zengindir.” Eğer entegrasyon odaklıysanız API key hızlı çözümdür;” daha geniş yetkilendirme gerekiyorsa OAuth öne çıkar.”\
“h3″>”API key’i düz metin olarak saklamak neden kötü?”
p>”Çünkü veritabanınız sızarsa tüm anahtarlar anında kullanılabilir hale gelir.” Hash saklamak riski ciddi biçimde azaltır.” Düz metin kayıt neredeyse davetiye gibidir.”\\
“
Tamamlanan isteklerde lastUsedAt tutmak şart mı?”
p>”Şart değil ama çok faydalıdır.” Hangi key’in aktif olduğunu görürsünüz,” kullanılmayanları ayıklarsınız,” support süreçleri hızlanır.”\\
“
Maksimum kaç API key vermek mantıklı?”
p>”Kullanıcının tipine göre değişir.” Küçük SaaS’larda üç ila beş arası iyi başlangıçtır.” Enterprise müşterilerde rol bazlı esneklik daha doğru olabilir.”\\
“\”
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
