API Anahtarı (API Key) Nedir?

Anahtar neyi kanıtlar, neyi kanıtlamaz?

API anahtarı, isteği gönderenin kayıtlı bir uygulama olduğunu gösterir; o uygulamayı hangi kişinin kullandığını söylemez. Google Cloud belgeleri de bunu açıkça vurgular: API anahtarları kullanıcıları değil projeleri tanımlar. Anahtar ayrıca taşıyıcı bir sırdır: eline geçiren herkes onu sahibinin yetkileriyle kullanabilir. Bu nedenle API anahtarı tek başına bir kullanıcı kimlik doğrulama yöntemi değildir.

Kullanıcıya ait verilere erişen, kapsamı ve süresi sınırlı bir yetkiye ihtiyaç duyulan senaryolarda doğru araç OAuth ile alınan bir erişim token'ıdır. API anahtarı ise sunucudan sunucuya entegrasyonlar, kota ve faturalama takibi, herkese açık verilere erişim gibi “hangi uygulama?” sorusunun yeterli olduğu durumlarda pratiktir.

Anahtar nasıl gönderilir?

# Önerilen: başlıkta
GET /v1/kurlar?baz=TRY HTTP/1.1
Host: api.example.com
Authorization: Bearer ak_live_7Hq2Lw9xNc4pR0tZ

# Kaçınılması gereken: URL'de
GET /v1/kurlar?baz=TRY&api_key=ak_live_7Hq2Lw9xNc4pR0tZ

Sağlayıcılar anahtarı Authorization başlığında ya da X-API-Key gibi özel bir başlıkta bekleyebilir. URL içinde taşınan anahtar ise sunucu loglarına, proxy kayıtlarına, tarayıcı geçmişine ve hata izleme araçlarına kopyalanır. Google da anahtarı başlıkla göndermeyi öneriyor ve sorgu parametresi kullanımının anahtarı URL taramaları yoluyla çalınmaya açık hâle getirdiğini belirtiyor.

Gizli anahtar ve yayımlanabilir anahtar

Pek çok servis iki tür anahtar verir. Gizli anahtar (secret key) yalnızca sunucuda yaşar ve ödeme oluşturmak, kullanıcı verisi okumak gibi güçlü işlemleri yapar. Yayımlanabilir anahtar (publishable key) ise tarayıcıda çalışan kodda bulunmak üzere tasarlanmıştır; harita göstermek ya da bir ödeme formunu başlatmak gibi sınırlı işler yapar ve herkesin görebileceği varsayılır. Bu tür anahtarları korumanın yolu gizlemek değil, kısıtlamaktır: yalnızca belirli alan adlarından (HTTP referrer), IP adreslerinden ya da belirli API'ler için geçerli olacak şekilde ayarlamak.

En sık karşılaşılan sızıntı, gizli anahtarın ön yüz koduna girmesidir. Next.js gibi framework'lerde NEXT_PUBLIC_ önekli ortam değişkenleri derleme sırasında JavaScript paketine gömülür; bu öneke gizli bir anahtar koymak onu her ziyaretçiye dağıtmak demektir.

Anahtarın yaşam döngüsü

• Üretim: Anahtar kriptografik olarak güvenli rastgele bir kaynaktan üretilmelidir. sk_live_ gibi okunabilir bir önek, sızan bir anahtarın hangi sisteme ait olduğunu tarama araçlarının tanımasını kolaylaştırır.
• Saklama (sağlayıcı tarafı): Anahtar kullanıcıya yalnızca bir kez gösterilmeli, veritabanında parola gibi özetlenmiş (hash) olarak tutulmalıdır.
• Saklama (kullanıcı tarafı): Kaynak koda, git deposuna veya ekran görüntülerine girmemeli; bir gizli bilgi yönetimi çözümünde ya da sunucunun ortam değişkenlerinde durmalıdır.
• En az yetki: Her entegrasyon için ayrı ve yalnızca gereken işlemlere izin veren anahtarlar oluşturun. Tek bir “her şeye yetkili” anahtar, sızıntının etkisini en büyük hâle getirir.
• Yenileme ve iptal: Kesintisiz geçiş için iki anahtarın bir süre birlikte geçerli olabildiği bir yenileme düzeni kurulmalı, sızıntı şüphesinde anahtar hemen iptal edilmelidir.
• İzleme: Kullanım anahtar bazında loglanmalı ve hız sınırlama anahtar başına uygulanmalıdır; olağandışı bir artış çoğu zaman sızıntının ilk işaretidir.

Anahtarın yetmediği yerler

Bir webhook'un gerçekten beklenen servisten geldiğini kanıtlamak için anahtarı istekle göndermek yerine gövdenin HMAC ile imzalanması tercih edilir; böylece sır hiçbir zaman ağ üzerinden geçmez. Yüksek güvenlik gerektiren servisler arası iletişimde ise karşılıklı TLS (mTLS) veya kısa ömürlü token'lar daha güçlü seçeneklerdir. Google'ın API anahtarı kullanım rehberi kısıtlama ve yenileme konusunda somut örnekler içeriyor.