- Konu sahibi
- #1
API anahtarı, bir uygulamanın başka bir servisin API'sine yaptığı istekte kendisini tanıtmasını sağlayan benzersiz karakter dizisidir. Servis bu anahtar sayesinde isteğin hangi proje veya uygulamaya ait olduğunu anlayabilir; erişim izni, kullanım kotası ve raporlama gibi kontrolleri uygulayabilir. Gönderim biçimi servise bağlıdır; anahtar bir istek başlığında veya belgenin belirttiği başka bir alanda taşınabilir.
Anahtarın anlamı sağlayıcıya göre değişir. Bazı anahtarlar yalnız proje, kota ve kullanım takibi içindir; bazıları gizli erişim yetkisi taşır. Bir anahtarın varlığı, uygulamanızın son kullanıcısının kimliğini doğruladığınız anlamına gelmez. Kullanıcı veya hizmet hesabı adına işlem yapılacaksa servisin yetki modeli ayrıca incelenmelidir.
Bir web uygulamasının hava durumu, harita, ödeme, e-posta veya yapay zekâ servisine istek gönderdiğini düşünün. Uygulama, servis sağlayıcının desteklediği yönetim yöntemiyle bir anahtar oluşturur. Daha sonra bu anahtarı API isteğine ekler. Sunucu anahtarı kontrol eder; anahtar geçerliyse, ilgili API etkinse ve kullanım kısıtları uygunsa isteği işler. Geçersiz, iptal edilmiş veya yetkisi yetersiz anahtarda genellikle kimlik doğrulama ya da yetki hatası döner.
Örnek bir istek şu yapıda olabilir:
Burada
Gizli erişim anahtarını sunucu tarafında bir sır yönetim sistemi veya yalnız sunucunun okuduğu ortam değişkeniyle sağlayın. Kaynak koda sabitlemeyin. Bazı derleme araçları ortam değişkenlerini istemci paketine aktarabildiğinden, değişkenin adına bakmak tek başına gizliliği kanıtlamaz. Tarayıcıda çalışan JavaScript'e, mobil uygulamanın içine veya herkese açık Git deposuna eklenen anahtar kullanıcılar tarafından görülebilir ve kopyalanabilir. İstemcide kullanılmak üzere tasarlanmış bir anahtarsa sağlayıcının desteklediği alan adı, uygulama paketi, IP adresi veya yalnızca gerekli API türleri için kısıtlama uygulanmalıdır.
Anahtarı parola gibi herkese açık kodda paylaşmak, tek anahtarı tüm projelerde kullanmak ve sınırsız yetki vermek en yaygın hatalardır. Ayrıca API anahtarını kullanıcı yetkilendirmesi sanmak da güvenlik açığı oluşturabilir. Kota hatasını kimlik doğrulama hatasıyla karıştırmamak için API'nin HTTP durum kodunu ve hata gövdesini birlikte inceleyin. Geliştirme, test ve üretim ortamları için ayrı anahtarlar kullanmak; erişim kayıtlarını izlemek ve kullanılmayan anahtarları kapatmak yönetimi kolaylaştırır.
Terimler tek başına aynı yetki modelini garanti etmez. Erişim belirteci bir kullanıcı adına olabileceği gibi bir uygulama veya hizmet hesabı adına da verilebilir. Anahtarın/belirtecin kapsamı, geçerlilik süresi, iptal yöntemi ve hangi kimliği temsil ettiği sağlayıcının belgesinden okunmalıdır.
Anahtarın anlamı sağlayıcıya göre değişir. Bazı anahtarlar yalnız proje, kota ve kullanım takibi içindir; bazıları gizli erişim yetkisi taşır. Bir anahtarın varlığı, uygulamanızın son kullanıcısının kimliğini doğruladığınız anlamına gelmez. Kullanıcı veya hizmet hesabı adına işlem yapılacaksa servisin yetki modeli ayrıca incelenmelidir.
Nasıl çalışır?
Bir web uygulamasının hava durumu, harita, ödeme, e-posta veya yapay zekâ servisine istek gönderdiğini düşünün. Uygulama, servis sağlayıcının desteklediği yönetim yöntemiyle bir anahtar oluşturur. Daha sonra bu anahtarı API isteğine ekler. Sunucu anahtarı kontrol eder; anahtar geçerliyse, ilgili API etkinse ve kullanım kısıtları uygunsa isteği işler. Geçersiz, iptal edilmiş veya yetkisi yetersiz anahtarda genellikle kimlik doğrulama ya da yetki hatası döner.
Örnek bir istek şu yapıda olabilir:
HTTP:
GET https://api.example.com/v1/weather?city=Ankara
X-API-Key: uygulamanizin_gizli_anahtariBurada
X-API-Key başlığı, servisin beklediği gönderim biçimlerinden yalnızca biridir. Bazı servisler anahtarı Authorization başlığında, bazıları da key gibi bir sorgu parametresinde ister. Doğru alan adı ve biçim ilgili API’nin belgesinden kontrol edilmelidir. Sağlayıcı destekliyorsa başlık kullanmak, anahtarın URL geçmişi ve erişim loglarına taşınması riskini azaltır.API anahtarı nerede kullanılmalı?
Gizli erişim anahtarını sunucu tarafında bir sır yönetim sistemi veya yalnız sunucunun okuduğu ortam değişkeniyle sağlayın. Kaynak koda sabitlemeyin. Bazı derleme araçları ortam değişkenlerini istemci paketine aktarabildiğinden, değişkenin adına bakmak tek başına gizliliği kanıtlamaz. Tarayıcıda çalışan JavaScript'e, mobil uygulamanın içine veya herkese açık Git deposuna eklenen anahtar kullanıcılar tarafından görülebilir ve kopyalanabilir. İstemcide kullanılmak üzere tasarlanmış bir anahtarsa sağlayıcının desteklediği alan adı, uygulama paketi, IP adresi veya yalnızca gerekli API türleri için kısıtlama uygulanmalıdır.
| Kullanım yeri | Risk | Uygun yaklaşım |
|---|---|---|
| Sunucu tarafı | Daha düşük görünürlük | Ortam değişkeni ve sunucu tarafı istek |
| Tarayıcı JavaScript'i | Anahtar ziyaretçiye görünür | Alan adı ve API kısıtlaması |
| Mobil uygulama | Anahtar uygulamadan çıkarılabilir | Uygulama kısıtlaması ve sınırlı yetki |
| Git deposu veya log | Hızlı sızıntı riski | Gizli değişken, maskeleme ve anahtar yenileme |
Uygularken izlenecek adımlar
- Kullanacağınız servisin yönetim panelinden yeni bir API anahtarı oluşturun.
- Anahtarı yalnızca ihtiyaç duyulan API'ler, projeler, alan adları veya IP adresleriyle sınırlandırın.
- Anahtarı kodun içine sabit yazmak yerine sunucunun ortam değişkenine kaydedin; örneğin
WEATHER_API_KEY. - İsteği, sağlayıcının beklediği başlık veya parametre adıyla gönderin.
- Önce geliştirme ortamında geçerli, kısıtlanmış ve hatalı anahtarla test yapın.
- Anahtarın sızdığını düşünüyorsanız kullanımını iptal edin veya yenileyin; yalnızca dosyadan silmek yeterli değildir.
Sık yapılan hatalar
Anahtarı parola gibi herkese açık kodda paylaşmak, tek anahtarı tüm projelerde kullanmak ve sınırsız yetki vermek en yaygın hatalardır. Ayrıca API anahtarını kullanıcı yetkilendirmesi sanmak da güvenlik açığı oluşturabilir. Kota hatasını kimlik doğrulama hatasıyla karıştırmamak için API'nin HTTP durum kodunu ve hata gövdesini birlikte inceleyin. Geliştirme, test ve üretim ortamları için ayrı anahtarlar kullanmak; erişim kayıtlarını izlemek ve kullanılmayan anahtarları kapatmak yönetimi kolaylaştırır.
Sık sorulan sorular
API anahtarı ile erişim belirteci aynı şey midir?
Terimler tek başına aynı yetki modelini garanti etmez. Erişim belirteci bir kullanıcı adına olabileceği gibi bir uygulama veya hizmet hesabı adına da verilebilir. Anahtarın/belirtecin kapsamı, geçerlilik süresi, iptal yöntemi ve hangi kimliği temsil ettiği sağlayıcının belgesinden okunmalıdır.
