API anahtarı rotasyonunu doğru yapın: kendi kendine hizmet eden anahtar yönetimini en az ayrıcalık kapsamları, kullanım kayıtları ve destek taleplerini azaltan güvenli UX ile tasarlayın.
API anahtarları başlangıçta basittir: bir anahtar, bir entegrasyon, iş biter. Sorun daha sonra ortaya çıkar; aynı anahtar paylaşılan bir tabloda, bir Slack mesajında veya artık kimsenin sahip olmadığı bir betik içinde sert kodlanmış olur. Bir anahtar kopyalanıp dağıtıldığında, kim kullanıyor ve neden kullanıyor gibi temel soruları cevaplama yeteneğini kaybedersiniz.
Hiç değişmeyen anahtarlar başka bir yaygın tuzaktır. Bir sızdırılan anahtar aylarca kötüye kullanım, beklenmedik faturalar veya veri açığa çıkmasına yol açabilir. Hiç “kötü” bir şey olmasa bile, eski anahtar yine de risk yaratır çünkü güvenle kaldırılabileceği çok fazla yerde yaşamaktadır.
İyi anahtar yönetimi sadece güvenlik ile ilgili değildir. Aynı zamanda olayları azaltır ve destek işini düşürür. Müşteriler kendi anahtarlarını görebildiklerinde, kısıtlayabildiklerinde ve güvenli şekilde değiştirebildiklerinde, ekibiniz manuel sıfırlamalar ve tahminlerle uğraşmayı bırakır.
“Self-servis” farklı roller için farklı anlamlar taşımalıdır. Yöneticiler genellikle tüm çalışma alanı üzerinde kontrol isterken, normal kullanıcılar yalnızca sahip olduklarını ya da bir yöneticinin devrettiği şeyleri yönetmelidir. Amaç, karmaşık izin labirenti yaratmadan net sahiplik ve net sınırlar sağlamaktır.
Güvenlik ve kullanılabilirlik birlikte çalışmak zorunda. UX acı verici olursa, insanlar bunu aşmak için her yerde tek bir “ana anahtar” kullanır. Pratik bir sistem en güvenli yolu en kolay yol yapar:
Örnek: bir ortak “API erişimi” istiyor. Tek seçeneğiniz tam erişim anahtarıysa, beklenenden fazlasını vermiş olursunuz. Self-servis akış, ortağın işine uyan dar bir anahtar vermenizi sağlamalıdır ve başka hiçbir şeyi.
Anahtar yönetimi, ilgili kişileri adlandırdığınızda ve sorumlulukları netleştirdiğinizde daha kolay olur. Çoğu ürün birkaç tekrar eden aktörle sonuçlanır: hesap sahibi (kuralları belirler ve faturayı öder), yöneticiler (çalışma alanı genelinde erişimi yönetir), geliştiriciler (anahtarları kodda kullanır ve döndürür), destek ("neden başarısız oldu?" sorusunu yanıtlar) ve denetçiler (erişimin kontrollü ve izlenebilir olduğunu doğrular).
Bir anahtar sadece gizli bir dize değildir. Bağlamı olan izinli bir kimlik bilgisi olarak görülmelidir. Anahtarları paylaşılan parolalar gibi ele alırsanız, bunu daha sonra rotasyon, olay müdahalesi ve temel hata ayıklama sırasında hissedersiniz.
Erken birkaç temel nesneyi tanımlayın:
Başarısızlık modları tahmin edilebilirdir: bir anahtar bir repoya veya sohbete sızar, kapsamlar “çalışması için” çok geniş olur ve kim hangi isteği yaptı söyleyemezsiniz. Sonuncusu destek yükü yaratır ve güvenlik işlerini yavaşlatır.
Ayrıca v1'de neyi desteklemeyeceğinize karar verin. Birçok ekip organizasyon geneli paylaşılan anahtarları, süresiz anahtarları ve tüm ortamlar arasında çalışan anahtarları ilk sürümde engeller. Bunları tasarımsal olarak imkansız kılmak, daha sonra denetlemeye çalışmaktan genellikle daha kolaydır.
En az ayrıcalık, insanlar doğru kapsamı birkaç saniyede seçebiliyorsa işe yarar. Bir güvenlik uzmanının anlaması gerekiyorsa, kullanıcılar “tam erişim”i seçip devam eder.
Başlangıç olarak, eylemleri iç hizmetler yerine bir insanın nasıl tarif edeceğini listeleyin. “Faturaları görüntüle” açık bir ifadedir. “billing.read” de olabilir, ama yalnızca UI bunu sade dilde de açıklıyorsa. Bu, rotasyon sırasında özellikle önemlidir çünkü müşterilerin yeni anahtarın eskisiyle eşleştiğine güvenmesi gerekir.
Kapsam setinizi küçük, istikrarlı ve gerçek işlerin etrafında gruplanmış tutun. Örneğin:
50 küçük anahtar seçeneğinden kaçının. Uzun bir liste genellikle kapsamların kodunuzu yansıttığı anlamına gelir, insanların nasıl çalıştığını değil.
Güvenli varsayılanlar yardımcı olur. Yaygın kullanım durumları için “önerilen paketler” sunun ve her paketin ne yaptığını açıkça gösterin. Örneğin, bir “Muhasebe entegrasyonu” paketi faturalar ve ödemeler için varsayılan olarak salt okunur olabilir, iadeler kapalı olur ve ileri düzey kullanıcıların özelleştirmesine izin verilebilir.
Yüksek riskli kapsamlar için kasıtlı sürtünme ekleyin. Bu, ekstra bir onay adımı, kapsam verme yetkisinin yalnızca yöneticiye verilmesi, zaman sınırlı yükseltme veya denetim kaydında sebep zorunluluğu gibi basit önlemler olabilir.
Örnek: bir ortak faturaları kendi sistemine eşitlemek istiyor. Onlara “faturaları oku” ve “müşterileri oku” verilmeli, “faturalamayı yönet” verilmemeli. Daha sonra iade yetkisine ihtiyaç duyarlarsa tek bir yükseltme isteyip onay alabilirler ve her şeyi yeniden düzenlemenize gerek kalmaz.
Varsayılan sayfa bir soruyu hızlıca cevaplamalı: “Şu anda hangi anahtarlar var ve bunlar güvende mi?” Basit bir tablo genelde en iyi sonucu verir: anahtar adı, ortam, durum (aktif, süresi dolmuş, iptal edilmiş), en son kullanım zamanı ve kısa kapsam özeti. Boş durum kullanıcıyı öğretmeli, utandırmamalı: “Henüz anahtar yok. Belirli bir uygulama veya ortak için yalnızca gerekli kapsamlarla bir tane oluşturun.”
Anahtar oluşturma, rastgele bir gizli değer üretmek gibi değil, izinleri ayarlamak gibi hissettirmeli. Akışı kısa tutun, sade etiketler kullanın ve kullanıcıların genellikle takıldığı yerlere küçük yardımcı metinler ekleyin.
İyi bir oluşturma formu genelde şunları içerir:
Gizliyi oluşturduğunuzda sadece bir kez gösterin ve nedenini basit sözlerle açıklayın: “Güvenliğiniz için ham gizliyi saklamıyoruz. Şimdi kopyalayın, çünkü bir daha göremeyeceksiniz.” Bir net eylem (kopyala) ve hafif bir onay ("Bu gizliyi güvenli bir yerde kaydettim") sağlayın.
İptal etme ve döndürme kolay bulunmalı ama kazara tetiklenmesi zor olmalı. Bunları “Yönet” menüsünün arkasına koyun ve etkiyi açık hale getiren ifadeler kullanın:
Rotasyonu destekliyorsanız, rehberli bir iletişim kutusu yardımcı olur: eski anahtar etiketi, yeni anahtar etiketi ve çağıran sistemi kesme süresinden önce güncelleme hatırlatıcısı gösterin.
Bir şey bozulduğunda, destek genelde aynı soruları sorar: hangi anahtar kullanıldı, ne yapmaya çalıştı ve ne değişti. İyi API kullanım kayıtları bu cevapları sunar ve sunucu günlükleri arasında kazı yapmayı gereksiz kılar.
Yararlı bir kayıt girdisi küçük ama spesifik olmalı ve taranıp filtrelenebilecek tutarlı alanlara sahip olmalıdır:
Kayıtları anahtar detay sayfasına bağlayın. İki küçük metrik birçok bileti önler: İlk görüldüğü tarih (anahtarın ilk kullanıldığı zaman) ve Son kullanma (en son istek). Bir anahtar “hiç kullanılmadı” gösteriyorsa, silinmesi için iyi bir adaydır. “En son kullanım” iki yıl öncesiyse, bir sonraki rotasyonda hayatta kalmamalıdır.
V1'de dışa aktarmadan çok filtreleme önemlidir. Filtreleri basit ve öngörülebilir tutun: zaman aralığı, durum (başarılı vs engellendi vs başarısız), eylem/kapsam ve ortam.
Saklama süresi bir ürün kararıdır, sadece depolama meselesi değil. Birçok ekip UI'da 30 ila 90 günle başlar ve yalnızca yöneticiler için daha uzun geçmiş tutar. Kullanıcıların günlüklerin “eksik” olduğunu varsaymaması için bunu arayüzde açıkça belirtin.
Rotasyon ancak öngörülebilir hissettirdiğinde işe yarar. Basit bir politika yayınlayın: anahtarların ne sıklıkla döndürüleceği (planlı) ve hangi olayların anında rotasyonu zorunlu kıldığı (olay-tetiklemeli). Planlı rotasyon örneğin her 90 gün olabilir. Olay-tetiklemeli rotasyon “çalışan ayrıldı”, “anahtar bir bilete yapıştırıldı” veya “olağandışı kullanım sıçraması” gibi durumlar olabilir.
En güvenli model örtüşmedir. Müşterilerin anahtarı tek bir anda değiştirmesini zorunlu bırakmayın. Yeni bir anahtar oluşturmalarına izin verin, eski anahtar hala çalışsın, sonra eskiyi belirli bir süreden sonra emekliye ayırın.
Pratik bir akış:
Gecikme süreleri önemli ama açık olmalı. Liste görünümünde anahtarın yanında bir son kullanma tarihi gösterin ve öncesinde uyarılar gösterin (örneğin: 14 gün, 3 gün, 24 saat). “Yakında süresi dolacak” gibi belirsiz metinlerden kaçının. Somut ifadeler kullanın: “Bu anahtar 30 Oca tarihinde 10:00 UTC'de çalışmayı durduracak.”
Hız limitleri ve kilitlenmeler hesapları korumalı ama normal davranışı cezalandırmamalıdır. Birçok istemci ağ zaman aşımından sonra yeniden dener, bu yüzden birkaç hataya dayalı kilitlenmeler yanlış alarmlara neden olabilir. Kuralları anlaşılır tutun:
Örnek: bir ortak API'nizi iki bölgeden kullanıyor. Rotasyon sırasında her iki anahtar da 7 gün çalışsın, böylece dağıtımları geceyarısı kesintisi veya destek bileti olmadan güvenle yapılabilir.
İyi izleme “güvenlik tiyatrosu”ndan çok şu soruyu hızlıca cevaplama ile ilgilidir: bu anahtar sahibinin beklediği şekilde mi kullanılıyor?
Anahtar listesinde insanlar tarafından hızlıca taranabilecek durum rozetleri gösterin. “Aktif” ve “İptal edildi” açıkken, “Yakında süresi dolacak” beklenmedik kesintileri önler. Basit bir “Son kullanım” zaman damgası (ve “Hiç kullanılmadı”) ekleyin ki ekipler eski anahtarları güvenle silebilsin.
Günlük görünümünüz ham isteklerden çok desenleri vurgulamalıdır. Kullanışlı olmak için gösterişli grafiklere gerek yok. Birkaç iyi seçilmiş sinyal çoğu sorunu yakalar:
Bildirimler nadir ve eyleme geçirilebilir olmalı. Her şeye alarm verirseniz, kullanıcılar sizi sessize alır ve önemli mesajı kaçırır. Pratik bir v1 seti:
Hassas kapsamlar için oluşturma, döndürme veya genişletme öncesi güçlü bir kapı (MFA veya onay adımı gibi) eklemeye değer. Bu, etkisi gerçek olan yerlerde kullanılmalı, her yerde değil.
İyi bir UI yanlış şeyler saklayan bir backend olursa yine başarısız olur. Amaç basit: anahtarları varsayılan olarak güvenli, denetlenebilir ve kötüye kullanılmaya zor olan hale getirmek.
Küçük ve net bir veri modeliyle başlayın. "Kim ne yaptı, ne zaman ve neden" sorusunu cevaplamak için yeterli alan istiyorsunuz, veritabanını gereksiz veri yığınına çevirmeden.
Pratik bir asgari set:
Kapsam modelinizi kararlı tutun. Kapsamları yeniden adlandırmak veya silmek entegrasyonları bozabilir ve günlükleri kafa karıştırıcı hale getirebilir.
API anahtarını bir parola gibi ele alın. Oluşturmadan sonra sadece tek yönlü bir hash (ve anahtar başına salt) saklayın. Destek ve UX için kısa, gizli olmayan bir tanımlayıcı saklayın, örneğin bir ön ek (örneğin “live_2F9K…”) ki kullanıcılar anahtarları ayırt edebilsin.
Rotasyon için yeni anahtar ile eski anahtar arasındaki ilişkiyi (rotated_from_key_id) saklayın. Bu, eski gizli değerleri saklamadan temiz bir geçmiş verir.
Her hassas değişiklik bir denetim olayı yaymalıdır: oluşturuldu, kapsam değişti, döndürüldü, iptal edildi ve “günlükler görüntülendi” gibi. Kim ne yapabilir sorusunu önceden karar verin. Yaygın bir kurulum: yöneticiler anahtarları yönetebilir ve tüm günlükleri görebilir; geliştiriciler kendi anahtarlarını yönetebilir ve kendi günlüklerini görebilir; destek/sadece görüntüleme rolleri gizli değerleri görmeden günlükleri görüntüleyebilir ama değişiklik yapamaz.
Rotasyonu destek kabusu haline getirmenin en hızlı yolu, güvensiz seçimleri normal hissettiren bir UI yayınlamaktır. Çoğu problem birkaç öngörülebilir tuzaktan gelir.
Varsayılan anahtar her şeyi yapabiliyorsa, çoğu insan bunu daraltmaz. İlk gördükleri anahtarı production'a yapıştırıp unutur.
Daha güvenli bir desen, minimum varsayılan kapsamlar ve bir şey başarısız olursa net hata mesajları sunmaktır, örneğin “eksik kapsam: invoices.read”. Eğer “tam erişim” gerekiyorsa, bunu açık bir seçim ve kısa bir uyarı ile sunun.
Anahtarların bir sahibi ve amacı olmalı. Bu alanlar yoksa sonra “Hangi anahtar bozuluyor?” ve “Bunu silebilir miyiz?” gibi destek biletleri alırsınız.
Oluşturma sırasında iki küçük girdi isteyin:
Rotasyon ayrıca yaygın bir kesinti tetikleyicisidir. Ani bir kesinti (eski anahtar anında devre dışı) zorlarsanız müşteriler kesinti yaşar. Örtüşmeyi sağlayın: yeni bir anahtar oluşturun, eski anahtar kısa bir süre geçerli kalsın, sonra devre dışı bırakın.
Günlükler genelde hangi anahtarın kullanıldığını göstermediği için başarısız olur. Yararlı bir kayıt; anahtar id'si (gizli değil), zaman damgası, uç nokta/eylem, ortam ve sonuç (başarılı/başarısız ve durum kodu) içermelidir. Sonuç kodları yoksa “kötü anahtar” mı, “eksik kapsam” mı yoksa “sunucu hatası” mı anlayamazsınız.
Gizli değeri oluşturduktan sonra bir daha asla göstermeyin ve e-posta ile göndermeyin. Ekran görüntülerinde, dışa aktarmalarda veya “takıma paylaş” akışlarında dahil etmeyin. Birisi onu kaybettiyse, çözüm basittir: yeni bir anahtar oluşturun ve döndürün.
Yayınlamadan önce hızlı bir destek ve güvenlik kontrolü yapın. İyi bir anahtar ekranı sadece anahtar oluşturmakla ilgili değildir. Güvenli seçimi kolay seçim haline getirmekle ilgilidir.
Bunu no-code bir araçla inşa ediyorsanız, bu noktaları UI gereksinimi olarak görün, “sonra iyileştirme” değil. Bunlar anahtar yönetiminin olayları azaltıp azaltmayacağını belirler.
Yaygın durum: bir lojistik ortağı sı shipment oluşturmak için sipariş verilerini çekmeye ihtiyaç duyuyor. Siparişleri değiştirmeye, iadeleri vermeye veya müşteri destek notlarını görmeye ihtiyaçları yok. Onlara tam erişim anahtarı verirseniz patlama alanını genişletmiş olursunuz.
Hızlı ama güvenli bir akış şu şekilde hissettirmeli: geliştirici portalınızda hesap sahibi “Logistics Partner - Orders Read” adlı yeni bir anahtar oluşturur. Salt okunur bir kapsam olan orders:read seçer (ve başka bir şey seçmez), bir son kullanım tarihi belirler (örneğin 90 gün) ve mümkünse partnerin sabit IP aralığı varsa IP ile kilitleyebilir.
Kopyalama adımını belirsiz bırakmayın: belirteci sadece bir kez gösterin ve net bir metin koyun: “Şimdi kopyalayın. Bu anahtarı bir daha görüntüleyemeyeceksiniz.” Bu tek cümle birçok destek biletini önler.
Birkaç gün sonra ortak “API kapalı” diye rapor ederse, kullanım kayıtlarınız gerçek soruyu saniyeler içinde cevaplamalıdır:
Bu senaryoda kayıtlar genelde basit bir problemi ortaya çıkarır: salt okunur bir anahtarla /orders/update çağrılıyor veya istekler izin verilen IP dışında yeni bir IP'den geliyor. Artık destek tahminde bulunmak yerine tek bir net düzeltme önerebilir.
Rotasyon iyi UX'in kendini kanıtladığı yerdir. Ortağın sözleşmeli çalışanı ayrıldığında, aynı orders:read kapsamı için yeni bir anahtar oluşturursunuz, her iki anahtar kısa bir örtüşme penceresinde geçerli olur ve entegrasyon yeni anahtarla doğrulandığında eski anahtar iptal edilir.
Başarı şöyle görünür: ortaklar ekibinizi beklemeden devreye girer, erişim varsayılan olarak minimal kalır ve bir şeyler bozulduğunda tam olarak ne olduğunu görüp hızlıca müdahale edersiniz.
Küçük başlayın. Temiz bir v1, aylar süren ama insanları hâlâ kafa karıştıran gösterişli bir portaldan iyidir. Çoğu ürün için kısa bir kapsam listesi, temel kullanım kayıtları ve tek bir güvenli rotasyon akışı gerçek ihtiyaçların çoğunu karşılar.
Üç yapı taşıyla başlayın: anahtarlar, kapsamlar ve günlükler. İlk etapta kapsamları kaba tutun (oku, yaz, yönetici) ve ihtiyaç kanıtı olmadan onlarca küçük izin eklemekten kaçının. Rotasyonu sıradanlaştırın: ikinci bir anahtar oluşturun, test edin, sonra eskiyi iptal edin.
Çalışan bir v1 için basit kontrol listesi:
V1 canlıya alındıktan sonra, destek biletlerini azalttığı sürece cilalama ekleyin. Günlük filtreleri (tarih aralığı, durum, uç nokta/eylem) genelde ilk kazanımdır. Uyarılar sonraki adımdır: sıçramalara, tekrarlayan kimlik doğrulama hatalarına veya uzun süren hareketsizlikten sonra ilk kullanıma bildirim gönderin. Hassas kapsamlar için her şeyi “yalnızca yönetici” yapmak yerine bir onay adımı ekleyin.
Ürünün içinde, eylemin yanında UX dokümantasyonu yayınlayın. Uzun belgeler yerine kısa yardımcı metinler daha iyidir: “Anahtarları çalışma saatlerinde döndürün. Trafiğin değiştiğini doğrulayana kadar her iki anahtarı da aktif tutun.”
Hızlı bir self-servis portalı hızla kurmak istiyorsanız, no-code yaklaşımı bunu iyi modelleyebilir: Keys tablosu, Scopes tablosu, Key-Scope ilişki tablosu, Logs tablosu ve yöneticiler ile destek için roller. AppMaster (appmaster.io) üzerinde PostgreSQL Data Designer'da veritabanını tasarlayabilir, Business Process Editor ile döndürme ve onayları uygulayabilir ve yönetici paneli ile müşteri portalı UI'sını bulut barındırma veya kaynak dışa aktarma seçenekleriyle yayınlayabilirsiniz.
21 Oca 2026
8 dk
20 Oca 20268 dk
20 Oca 20268 dkÜcretsiz planla AppMaster ile denemeler yapın.
Hazır olduğunuzda uygun aboneliği seçebilirsiniz.
