API anahtarları için ortam değişkenlerini teknik olmayan geliştiriciler için açıklar: anahtarları prompt'lardan ve repolardan uzak tutun, dev/staging/prod eşlemesi yapın ve güvenli şekilde döndürün.
Bir API anahtarı, uygulamanızın konuştuğu bir hizmet için (ödeme, e-posta, haritalar, AI, analiz) bir şifre gibidir. Bu, o hizmete "bu istek hesabımdan geliyor" der; hizmet de sizi ücretlendirir, limitleri uygular ve erişim izni verir.
Anahtarlar genellikle hızlı bir kopyala-yapıştır ile başlar; bir sohbete, ayar dosyasına veya "şimdilik" diye bir not'a yapıştırırsınız ve sonra istemeden paylaşılabilecek bir yere kaydedilir.
Yaygın kazara sızma yolları: prompt'lara yapıştırmak (özellikle hızlıca vibe-coding araçlarında çalışırken), bir repo'ya commit etmek veya "inceleme için" zip yüklemek, bir ekran görüntüsüne veya ekran kaydına anahtar koymak, ortak bir dokümanda ya da ekip sohbetinde bırakmak veya ön uç koduna gömmek — tarayıcıdaki herkes bunun içeriğini okuyabilir.
Risk soyut değildir. En hızlı acı sürpriz faturalar: birisi anahtarınızı kullanıp API'yi binlerce kez çağırabilir. Bir sonraki risk veri erişimi: anahtar müşteri verilerini okuyabiliyor veya e-posta gönderebiliyorsa saldırgan da aynı şeyi yapabilir. En kötü durumda geniş izinli bir anahtar yeni anahtarlar oluşturabiliyorsa hesap ele geçirilmesine yol açabilir.
Çoğu faydayı almak için güvenlik uzmanı olmanıza gerek yok. Küçük bir alışkanlık değişikliği büyük fark yaratır: anahtarları "gizli" olarak ele alın ve prompt'ların ve repo'ların dışında tutun. İşte ortam değişkenlerinin tam olarak yaptığı şey: gizliyi korunan bir yerde saklayın ve uygulamanız çalışırken onu okusun, kodunuza veya ekran görüntülerinize gömmeyin.
Bir kural aklınızda kalsın: kod uygulamanızın ne yaptığını, yapılandırma nasıl davrandığını ve gizli veriler asla açığa çıkarmamanız gereken şeyleri tanımlar.
Kod: oluşturduğunuz mantık (ekranlar, butonlar, hesaplamalar, API çağrıları). Takımla paylaşılabilir olmalı ve genelde bir repo'ya gider.
Yapılandırma: zarara yol açmayacak ayarlar. Örneğin uygulama adınız, hangi bölgede çalışacağı, feature flag'ler veya bir hizmetin temel URL'si. Görülse zarar vermemeli.
Gizli veriler: krallığın anahtarları: API anahtarları, veritabanı parolaları, özel tokenlar, imzalama anahtarları. Bir yabancı bunlara ulaşırsa uygulamanız gibi hareket edebilir.
Ortam değişkeni, uygulamanızın çalışırken okuduğu etiketli bir yuva gibidir. Kod STRIPE_SECRET_KEY gibi bir etiketi arar ve o anda orada ne varsa kullanır. Bu ayrım, ortam değişkenlerinin API anahtarları için neden iyi çalıştığını açıklar: kod aynı kalırken gizli değer prompt'ların, dosyaların ve repo'nun dışında tutulur.
Kod ile gizlileri ayrı tutmak düzeltmeleri de kolaylaştırır. Bir gizli yanlışlıkla sızdıysa, kodu değiştirmeden değeri yenileyebilirsiniz.
Ortamlar için pratik düşünce: aynı etiketler, farklı değerler.
Örneğin PAYMENTS_KEY etiketini her yerde kullanabilirsiniz; ama dev test anahtarı, staging kısıtlı bir anahtar ve prod tam canlı anahtar kullanır. Koder.ai gibi bir platformda deploy ediyorsanız, aynı uygulamayı farklı ortamlar için farklı ortam ayarlarıyla dağıtmak bu modele iyi uyar.
Gizli, birine verilmemesi gereken güç sağlayan her değerdir. Bir yabancı alırsa giriş yapabilir, paranızı harcayabilir, özel verileri okuyabilir veya uygulamanızmış gibi davranabilir.
Yaygın gizliler: API anahtarları, veritabanı parolaları, özel erişim tokenları, imzalama anahtarları ve webhook sırları. Bir şey oluşturuyor, siliyor, ücretlendiriyor, özel veri okuyor veya istekleri imzalayabiliyorsa gizli olarak ele alın.
Bazı değerler zararsız gibi görünür ama hassastır. Yazma yetkisi veren tokenlar klasik tuzaktır: parola gibi görünmeyebilirler ama saldırganın değişiklik göndermesine, dosya yüklemesine, e-posta göndermesine veya veritabanına yazmasına izin verir. Admin anahtarları, servis hesabı JSON dosyaları ve uzun rastgele görünen tokenlar için aynı kural geçerlidir.
Her şey gizli işlemeyi gerektirmez. Genelde gizli olmayanlar: sadece UI veya davranışı değiştiren feature flag'ler, genel URL'ler, UI metinleri, analytics ölçüm ID'leri ve tek başına veri erişimi sağlamayan iç ID'ler. Önyüzde veya dökümana görünmesi amaçlanan birşey muhtemelen gizli değildir.
Hızlı test: bunu kamuya açık bir sohbete yapıştırılmış veya herkese açık bir repo'ya commit edilmiş görseniz kızar mıydınız? Cevap evet ise gizlidir.
Kullanılan gizlilerin küçük bir yazılı listesini tutun. Her biri için ne için olduğunu (ödeme, e-posta, veritabanı, depolama), nerede bulunması gerektiğini (dev, staging, prod), kime ait olduğunu (siz, bir ekip arkadaşı, bir satıcı hesabı) ve salt okuma mı yoksa yazma izni mi gerektiğini not edin. Bu liste anahtarları döndürürken tahminden kaçınmanızı sağlar.
Çoğu sızıntı "hacker" değil. Birisi bir değeri kopyalayıp çözüme hızlıca ulaşmak için yapıştırır, sonra unutulur. İyi bir kural: aranabilir, senkronize edilebilir, iletilebilir veya ekran paylaşılabilir her şeyi halka açık kabul edin.
Sohbet büyük bir kaynak. İnsanlar tam API anahtarlarını prompt'lara, ekip sohbetlerine veya destek mesajlarına yapıştırıyor çünkü hızlı geliyor. Yardıma ihtiyaç duyarsanız sadece son 4–6 karakteri ve anahtar adını yapıştırın, örneğin STRIPE_SECRET_KEY ...9f2a.
Git klasik bir tuzak. Bir anahtarı "şimdilik" bir dosyaya ekleyip commit edersiniz ve sonra silseniz bile commit geçmişinde kalır. Forklar, kopyalanan snippet'ler veya pull request farklarıyla da yayılabilir.
Ekran görüntüleri ve ekran kayıtları insanların sandığından daha fazla sızdırır. Bir demo video ayarlar ekranını, bir terminal komutunu veya token gösteren hata mesajını yakalayabilir. Bulanıklaştırılmış metin bile riskli olabilir.
Issue takipçileri ve not uygulamaları başka sessiz bir kaynaktır. Ticket'lar, kontrol listeleri ve paylaşılan dokümanlar takımlar ve satıcılar arasında kopyalanır. Bunları kamu kayıtları gibi düşünün.
Birkaç alışkanlık çoğu sızmayı engeller:
Koder.ai'de geliştiriyorsanız aynı zihniyeti koruyun: hassas değerleri uygulamayı tanımlayan sohbete koymayın, ortam ayarlarında tutun.
Amaç basit: uygulamanız gizlileri ortamdan okumalı; prompt'tan, koddan veya Git'e gidebilecek dosyalardan değil.
.env dosyası makinenizdeki basit bir metin dosyasıdır ve anahtar-değer çiftleri saklar. Yerel kurulum kolaydır ama aynı zamanda kolayca sızar, bu yüzden bir cüzdan gibi davranın.
Yerel olarak bir .env dosyası oluşturun ve Git tarafından yok sayıldığından emin olun (genellikle .gitignore ile). Değişken isimlerini takım arkadaşlarınızla paylaşmanız gerekiyorsa, sadece yer tutucu içeren .env.example dosyası paylaşın; gerçek değerleri asla koymayın.
Herkesin yanlış tahmin etmesini engelleyecek açık adlar seçin:
OPENAI_API_KEYSTRIPE_SECRET_KEYDATABASE_URLSENDGRID_API_KEYS3_ACCESS_KEY_IDİyi adlar, dev, staging ve prod'u ayarlarken hataları azaltır.
Uygulama başlarken işletim sistemine sorar: "OPENAI_API_KEY için bir değer var mı?" Değer varsa uygulama onu kullanır. Eksikse uygulama erken hata verip çalışmaktan kaçınmalıdır.
Pratik alışkanlık: bir değişkenin var olup olmadığını log'layın (evet/hayır), ama gizlinin kendisini asla yazdırmayın.
Anahtarları sohbetlere veya ticketlara yapıştırmayın. Bir parola yöneticisi (paylaşılan kasa) veya başka güvenli bir kanal kullanın ve kişiye sadece ihtiyacı olanı verin. Birisi takımdan ayrıldığında anahtarı döndürün.
Örnek: bir kurucu bir Koder.ai projesini dışa aktarır ve yerelde çalıştırır. .env dosyasını laptopunda tutar, sadece .env.example commit eder ve gerçek anahtarlara erişim için takımın paylaşılan parola yöneticisini kullanır.
Ortamları üç ayrı oda diye düşünün.
Dev laptopunuz veya kişisel sandbox'ınızdır; hızlı değişiklikler yaparsınız. Staging üretimin güvenli bir kopyasıdır; tam uygulamayı test edersiniz ama gerçek müşteri etkisi olmaz. Prod müşterilerin kullandığı ortamdır.
Basit kural: değişken adlarını her yerde aynı tutun, sadece değerleri değiştirin. Kod tüm ortamlarda STRIPE_SECRET_KEY'i okur; ama her ortam farklı bir anahtar sağlar.
Küçük bir eşleme tablosu (basit bir not bile) yardımcı olur:
| Değişken adı (her yerde aynı) | Dev değeri | Staging değeri | Prod değeri |
|---|---|---|---|
PAYMENTS_API_KEY | test anahtar | staging anahtar | canlı anahtar |
APP_BASE_URL | localhost URL | staging domain | özel domain |
DATABASE_URL | lokal DB | staging DB | prod DB |
Prod, dev anahtarlarını tekrar kullanmamalı. Dev anahtarları genelde takım içinde paylaşılıyor ve bazen geniş izinlere sahip olabiliyor.
Küçük bir takımda ortam değerlerini düzenli tutmak için birkaç kural belirleyin:
STRIPE_KEY vs STRIPE_API_KEY gibi kopyalardan kaçının).Koder.ai gibi barındırılan bir builder kullanıyorsanız, her dağıtım hedefini (dev, staging, prod) kod aynı olsa bile ayrı ortamlarla düşünün.
Bir gizliyi döndürmek, bilinçli olarak bir API anahtarını değiştirmek demektir. Doğru yapıldığında, döndürme sıkıcıdır: anahtarı değiştirirsiniz, her şeyin çalıştığını doğrularsınız, sonra eski anahtarı devre dışı bırakırsınız.
En güvenli zihniyet: "kısa süreli iki anahtar." Birçok sağlayıcı birden fazla aktif anahtar oluşturmanıza izin verir. Bu örtüşme uygulamanızın çalışmaya devam etmesini sağlar.
Basit döndürme penceresi:
Eğer sağlayıcı birden fazla aktif anahtar desteklemiyorsa düşük trafikli bir zaman seçin ve kısa bir kesinti bekleyin. Amaç aynı kalır: kodu değiştirmeden gizliyi bir yerde değiştirmek.
Eğer bir anahtarın sızdığını düşünüyorsanız önce harekete geçin, sonra inceleyin. Anahtarı hemen iptal edin, yeni bir tane oluşturun ve ortam değişkeninizi güncelleyin. Uygulama stabil olunca nereden kaçtığını araştırın: chat prompt'ları, build log'ları, ekran görüntüleri, eski commit'ler veya paylaşılan dokümanlar.
Örnek: Koder.ai'de küçük bir CRM yaptınız ve e-posta API'si kullanıyor. Yeni bir e-posta anahtarı oluşturursunuz, uygulamanın ortam ayarlarına koyarsınız, test e-posta gönderirsiniz, sonra eski anahtarı iptal edersiniz.
CI/CD, push ettiğinizde uygulamanızı inşa eden ve dağıtan otomatik bir boru hattıdır ve genelde uygulamanızın ihtiyaç duyduğu aynı gizlilere ihtiyaç duyar.
Ana kural: API anahtarlarını build log'larına, kaynak koda veya sohbet prompt'larına sokmayın. Pipeline'ı kontrollü bir bilgisayar olarak düşünün: gizlileri kontrollü şekilde almalı.
Build adımında gereken gizliler ile çalışma zamanında gerekenleri ayırmaya çalışın.
Build-zamanı gizliler sadece build sırasında gerekli olanlardır (ör. özel bir paketi indirmek için). Çalışma-zamanı gizliler deploy sonrası gerekir (ör. Stripe çağrıları, e-posta gönderme). Eğer anahtarları sadece çalışma-zamanında tutabiliyorsanız, onların bir bundle'a gömülme veya build çıktısında cache'lenme ihtimalini azaltırsınız.
Hızlı bir kontrol: gizli kullanıcı tarayıcısında görünüyorsa bu gizli değildir. Tarayıcıda görünmesi gereken "public key"'ler olabilir; ama sunucu API anahtarları sunucuda kalmalı.
Barındırma platformunuzun ortam-özel gizli depolama alanını kullanın ki dev, staging ve prod farklı değerlere sahip olsun.
Koder.ai hosting ile deploy ediyorsanız, ortam başına ortam değişkenleri olarak gizlileri ayarlayın; kod veya konfigürasyon dosyalarına yapıştırmayın. Uygulama çalışma zamanında onları okur (PAYMENTS_API_KEY prod'da canlı, staging'de test gibi).
Production güvenliğini korumak için prod gizlilerini görüntüleyebilen kişileri sınırlayın. "Gizlileri gör" grubunu küçük tutun ve araç izinleri izin veriyorsa deploy izinlerini gizli düzenleme izinlerinden ayırın. Ayrıca her ortam için ayrı anahtarlar kullanın ki staging prod verilerine erişemesin.
Çoğu sızıntı günlük kestirmelerden doğar ve sonra sonraki projeye de bulaşır.
.env'i commit etmek)Anahtar kaynak dosyalarınızdaysa, yedekler, ekran görüntüleri, paylaşılan zip'ler ve git geçmişinde yer alır.
Düzeltme:
.env'i ilk commit'ten önce ignore dosyanıza ekleyin.Gerçek bir anahtarı bir sohbete yapıştırdığınızda artık o metnin nerede saklandığını veya kopyalandığını kontrol edemezsiniz. Vibe-coding araçlarında her şeyi sohbete atmak cazip olabilir. Bunun yerine PAYMENTS_API_KEY=REDACTED gibi yer tutucular kullanın ve sorunu tarif edin.
İyi alışkanlık: hata mesajlarını kopyalayın, kimlik bilgilerini asla kopyalamayın.
Tek bir anahtarın dev, staging ve prod arasında kullanılması, bir sızıntı olduğunda hasarı büyütür. Birden çok kişi aynı anahtarı paylaşıyorsa kimin kullandığını da ayrı izleyemezsiniz.
Düzeltme: her ortam için ayrı anahtar oluşturun; sağlayıcı destekliyorsa kişi başına veya uygulama başına ayrı anahtarlar kullanın.
Başlangıçta "tüm konfigürasyonu" yazdırmak yaygındır; bu genelde tokenları içerir.
Düzeltme: sadece ihtiyaç duyduğunuzu loglayın (ör. "Stripe key yüklendi: evet"), gerekiyorsa değerlerin maskelenmiş halini gösterin (son 4 karakter gibi).
Örnek: staging çalışmıyorsa tam anahtarı yazdırmayın. STRIPE_KEY ending in 9K2P gibi gösterin ki doğru anahtarı deploy edip etmediğinizi doğrulayabilesiniz.
Göndermeden önce sadece gizlilere odaklanan sakin bir geçiş yapın.
api_key, secret, token ve sağlayıcı isimleri gibi desenleri arayın. Paylaşılan dokümanları, ekran görüntülerini ve yapıştırılmış chat kayıtlarını da kontrol edin. Bir anahtar bir kez git'e veya dokümana çıktıysa onu harcanmış kabul edip değiştirin.Hızlı örnek: uygulamanız ödeme ve e-posta API'si kullanıyorsa, dev, staging ve prod için iki ayrı anahtar setiniz olmalı ve her birinin açık sahibi bulunmalı. Deploy ederken (hosting veya Koder.ai gibi bir platformla) doğru env var'ları doğru ortama haritalayın; bunları prompt'lara, koda veya repo'ya yapıştırmayın.
Maya teknik olmayan bir kurucu ve basit bir web uygulaması yapıyor: kullanıcılar abonelik için ödeme yapıyor ve uygulama makbuz ile şifre sıfırlama e-postaları gönderiyor. Prompt'ları ve repo'yu temiz tutmak için gizlileri kodun dışında ayarlar olarak ele alıyor; çalışma zamanında ortam değişkenleri ile enjekte ediyor.
Maya'nın tanımladığı küçük ve pratik env var listesi (isimler her yerde aynı, sadece değerler değişir):
APP_ENV = development / staging / productionAPP_BASE_URL = http://localhost:3000 / https://staging.example.com / https://example.comPAYMENTS_PROVIDER_SECRET_KEY = test anahtarı (dev) / test anahtarı (staging) / canlı anahtar (prod)EMAIL_PROVIDER_API_KEY = sandbox anahtarı (dev) / kısıtlı anahtar (staging) / tam yetkili anahtar (prod)DATABASE_URL = lokal DB (dev) / staging DB (staging) / production DB (prod)Basit kural: dev ve staging test modlarında ve ayrı veriler kullanmalı. Production canlı anahtarları ve gerçek verileri kullanır. Böylece staging'de yapılan bir hata gerçek kartlardan para çekmez veya gerçek müşterilere e-posta göndermez.
Gerçekçi bir döndürme olayı: bir yüklenici erişimi varken takımdan ayrıldı. Maya eski anahtarların sızmış olabileceğini varsayar. Ödeme ve e-posta panellerinde yeni anahtarlar oluşturur, her ortamın değerlerini günceller ve önce prod'u sessiz bir zaman diliminde döndürüp doğruladıktan sonra staging ve dev'i günceller. Bir sorun çıkarsa hızlıca önceki bilinen iyi konfigürasyona geri döner.
Sonrasında karışıklığı önlemek için:
Eğer zaten Koder.ai (koder.ai) ile inşa ediyorsanız, dağıtımlar ve ortam ayarlarını tek bir yerde tutmak işleri düzenli tutar. Snapshot ve rollback özellikleri bir konfigürasyon değişikliği kesintiye yol açtığında hızlı kurtarma sağlar.
Bir API anahtarı hızla beklenmedik faturalara yol açabilir ve bazen özel verilere erişim veya e-posta gönderme gibi işlemler yapma yetkisi verebilir. Bir parola gibi düşünün: başkasının eline geçerse genellikle uygulamanızmış gibi işlem yapabilir.
Sırları ortam değişkenlerine koyun, böylece gerçek değer kodunuzun dışında ve herhangi bir yere yapıştırdığınızda, commit ettiğinizde veya ekran görüntüsü aldığınızda görünmez olur. Uygulamanız çalışma zamanında STRIPE_SECRET_KEY gibi isimle değeri okur; kod paylaşılabilir kalır.
Bir yabancının para harcamasına, özel verilere erişmesine veya uygulamanız gibi davranmasına olanak veriyorsa, o değeri gizli kabul edin. API anahtarları, veritabanı parolaları, özel tokenlar, imzalama anahtarları ve webhook sırları gizlidir; halka açık kimlikler ve sadece UI ile ilgili ayarlar genelde değildir.
En sık sızmalar sohbet prompt'ları, ekip sohbetleri, destek ticket'ları, ekran görüntüleri ve git commit'leri (commit geçmişi dahil) aracılığıyla olur. Aranabilir, senkronize edilebilir, iletilebilir veya ekran paylaşılabilir her şeyi muhtemelen ortak kabul edin.
Yerel kullanım için .env dosyası uygun, ama asla onu commit etmeyin. .env makinenizde kalsın; takım arkadaşlarınızla paylaşmanız gerekiyorsa sadece placeholder içeren .env.example dosyası paylaşın.
Her ortamda aynı değişken adlarını kullanıp sadece değerleri değiştirin. Örneğin PAYMENTS_API_KEY hem dev'de hem staging'de hem prod'da var, ama dev test anahtarı kullanır, prod canlı anahtar kullanır.
Hayır. Sunucu API anahtarları ön uç kodunda asla olmamalı çünkü herkes tarayıcıda bunları okuyabilir. Güvenli olması gereken çağrılar için isteği backend'inizden yönlendirin ve gizli değeri sunucuda tutun.
Önce yeni bir anahtar oluşturun (eskiyi hemen silmeyin). Ortam değişkenini güncelleyin, uygulamayı yeniden başlatın veya deploy edin, gerçek akışı doğrulayın (test e-posta, test ödeme vb.), sonra eski anahtarı iptal edin.
Hemen anahtarı iptal edin veya devre dışı bırakın, ardından yeni bir anahtar oluşturup ortam ayarlarını güncelleyin ve yeniden deploy edin. Uygulama stabil hale geldikten sonra nereden sızdığını araştırın (chat logları, commit'ler, ekran görüntüleri, eski dokümanlar).
Ortam ayarlarında ortam başına saklayın ve proje sohbeti ile kaynak kodu dışında tutun. Bir konfigürasyon değişikliği sorun yaratırsa, snapshot ve rollback ile bilinen iyi duruma geri dönün. Koder.ai kullanıyorsanız ortam ayarlarını her deployment hedefi için ayrı tutun.