Stripe API Anahtarları Açıklandı: Test ve Canlı, Yayınlanabilir ve Gizli, Kısıtlı Anahtarlar

Her Stripe entegrasyonu aynı soruyla başlar: hangi anahtar nereye gider? Stripe size bir yayınlanabilir anahtar, bir gizli anahtar ve kısıtlı anahtarlar oluşturma seçeneği sunar; her biri test ve canlı olmak üzere iki türdedir. Yanlış olanı yanlış yere koyarsanız ya para taşıma yeteneğini sızdırırsınız ya da bir 401 hatası yüzünden öğleden sonranızı kaybedersiniz. Bu kılavuz, her Stripe API anahtarının ne yaptığını, nerede bulunduğunu, ilk test modu isteğinin nasıl gönderileceğini ve canlı anahtarın paylaşılan hiçbir şeyde bulunmamasını nasıl sağlayacağınızı kapsar. Önce genel kavram için, API anahtarı nedir ile başlayın. Aşağıdaki her şey, Eylül 2026'da kontrol edilen Stripe'ın API anahtarları belgelerini takip eder.

Stripe API anahtarlarınızın Kontrol Panosunda nerede olduğu

API anahtarları sayfasını dashboard.stripe.com/apikeys adresinde açın. Kontrol Panosunda Developers (Geliştiriciler) altında bulunur ve görüntülediğiniz hesap veya sanal alan için anahtarları gösterir. Bir geçiş düğmesi, sanal alan modu ile canlı mod arasında geçiş yapar ve anahtar listesi de bununla birlikte değişir.

Sayfada iki liste vardır:

• Standart anahtarlar yayınlanabilir anahtarınızı ve gizli anahtarınızı tutar.
• Kısıtlı anahtarlar kapsamlı izinlerle oluşturduğunuz anahtarları tutar.

Görünürlük moda göre değişir. Bir sanal alanda her anahtarı istediğiniz zaman görüntüleyebilirsiniz. Canlı modda, kendiniz oluşturduğunuz bir gizli anahtar, oluşturma sırasında yalnızca bir kez gösterilir. İletişim kutusunu kapatmadan önce anahtarı kasanıza kopyalayın; kaybetmek, onu döndürmeniz anlamına gelir. Canlı modda yalnızca Stripe'ın oluşturduğu varsayılan anahtarlar yeniden görüntülenebilir.

Sayfanın göstermeyeceği bir şey: webhook imzalama sırları. Bunlar Webhooks (Web kancaları) altında, uç nokta başına bulunur ve hiç API anahtarı değildir.

Yayınlanabilir ve gizli anahtarlar

İsimler güven sınırını tanımlar.

Yayınlanabilir anahtar tarayıcıya veya mobil uygulamaya aittir. Bir kart numarasını token'a dönüştürür ve pek başka bir şey yapmaz. Ödeme oluşturamaz veya hesap verilerini okuyamaz, bu nedenle ön uç kodunda gönderilmesi beklenir.

Gizli anahtar sunucunuza aittir ve başka hiçbir yerde olmamalıdır. Stripe'ın yönlendirmesi değişti: belgeler artık 'yeni kullanım durumları için gizli anahtarların kullanılmasını önermiyoruz' diyor ve bunun yerine kısıtlı anahtarlara işaret ediyor. Kısıtlanmamış gizli anahtar hâlâ çalışır, ancak onu varsayılan değil, acil durum çözümü olarak görün.

Test ve canlı mod anahtarları

Stripe iki ayrı dünya işletir, her birinin kendi anahtar seti vardır. Test anahtarları (yeni belgeler test tarafını sanal alan olarak adlandırır, ancak önekler hâlâ _test_ der) simüle edilmiş nesneler döndürür: sahte müşteriler, sahte PaymentIntent'ler, komutla başarılı veya reddedilen test kartları, gerçek para yok. Canlı anahtarlar kart ağlarına erişir ve gerçek fonları taşır.

Ayrım katıdır. sk_test_ ile oluşturulan bir müşteri, sk_live_ açısından mevcut değildir ve bunun tersi de geçerlidir. Stripe'ın akışları karıştırma için hata kodu olan livemode_mismatch, bunu açıkça söyler: 'Test ve canlı mod API anahtarları, istekleri ve nesneleri yalnızca karşılık gelen mod içinde kullanılabilir.'

İki pratik kural vardır:

• Tamamen sk_test_ veya rk_test_ ile geliştirin ve test edin. Stripe, yeni entegrasyonlar için ayrı bir genel sanal alan önerir, böylece ayarları ve verileri izole kalır.
• Canlıya geçiş bir yapılandırma değişikliğidir, kod değişikliği değil. Sunucunuz anahtarı bir ortam değişkeninden veya kasadan okur ve canlıya geçmek o değeri değiştirmek anlamına gelir.

Her API yanıtı bir livemode boolean değeri içerir. Testlerinizde bunu doğrulayın; yanlış anahtarla dağıtıma karşı en ucuz korumadır.

Kısıtlı anahtarlar ve en az yetki

Kısıtlı API anahtarı (Stripe bunu RAK olarak kısaltır) izin maskeli bir gizli anahtardır. Bir tane oluşturduğunuzda, her kaynak grubu için bir izin seçersiniz: Yok, Okuma veya Yazma. Her şey varsayılan olarak Yok'tur. Yazma, Okumayı içerir ve HTTP eşlemesi basittir: GET Okuma gerektirir, POST ve DELETE Yazma gerektirir.

Bir tane oluşturmak için, API anahtarları sayfasında Kısıtlı anahtar oluştur'a tıklayın, önceden yapılandırılmış bir izin seti seçin veya sıfırdan başlayın, adlandırın, izinleri ayarlayın ve iki faktörlü istemi tamamlayın. Canlı modda kendi oluşturduğunuz gizli anahtarda olduğu gibi, değeri bir kez görürsünüz.

Kısıtlı anahtarlar kılavuzu hizmet başına bir anahtar önerir: bir faturalama hizmeti Faturalar ve Müşteriler üzerinde Yazma alır, bir raporlama işi Ödemeler ve İtirazlar üzerinde Okuma alır. Bir hizmet tehlikeye girerse, saldırgan o anahtarın izinleriyle sınırlanır. Salt okunur bir itiraz anahtarı ödeme oluşturamaz veya bir ödemeye dokunamaz.

Yeni bir anahtara bir sanal alanda geniş izinler verin, test paketinizi çalıştırın, ardından anahtarın istek günlüklerini açın (taşma menüsü, İstek günlüklerini görüntüle) ve trafik görmeyen her izni budayın. Stripe ayrıca otonom AI ajanları için amaçlanan anahtarları etiketlemenize olanak tanır, böylece ödemeler ve iadeler için onay kurallarına tabi olurlar; düz bir gizli anahtar yerine bu yolu kullanın.

curl ve Python ile ilk isteğiniz

Stripe, HTTP Basic Auth ile kimlik doğrular: anahtar kullanıcı adıdır ve parola boştur. Sondaki iki nokta curl'e soru sormamasını söyler:

export STRIPE_API_KEY=sk_test_...   # your sandbox secret key

curl https://api.stripe.com/v1/payment_intents \
  -u "$STRIPE_API_KEY:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true"

Yanıt, pi_ ile başlayan bir id, status: "requires_payment_method" ve livemode: false içeren bir PaymentIntent'tir. Bu son alan, bir test anahtarı kullandığınızı doğrular.

Stripe ayrıca -H "Authorization: Bearer $STRIPE_API_KEY" biçimini kabul eder; Apidog ve çoğu HTTP istemcisi bu biçimi kullanır. Her ikisi de aynı anahtarı taşır; hangi stilin yığınınıza uyduğundan emin değilseniz, API anahtarları ve bearer token'lar karşılaştırmamız ödünleşimleri ele alır. İstekler HTTPS üzerinden gitmelidir; düz HTTP, kimlik doğrulama referansına göre doğrudan başarısız olur.

Python'da, güncel SDK deseni, anahtarı ortamdan okuyan bir StripeClient'tır:

import os
import stripe

client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])

intent = client.v1.payment_intents.create({
    "amount": 2000,
    "currency": "usd",
    "automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode)  # pi_..., False

Dosyada hiçbir anahtar dizesi görünmez. Aynı kod, ortamın sağladığına bağlı olarak test veya canlıya karşı çalışır.

Kodlama ajanınızın Stripe anahtarını Apidog CLI ile test etmesine izin verin

Curl, anahtarın bir kez çalıştığını kanıtlar. Kodlama ajanınız bunu Apidog CLI aracılığıyla tekrarlanabilir bir kontrol haline getirebilir ve anahtarı paylaşılan projeden uzak tutabilir. Bir kez kurun (token, Hesap Ayarları, API Erişim Token'ı altındadır):

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Ardından ajana bir istem verin:

Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.

Çalıştırdığı komutlar, Apidog CLI 2.2.7'ye göre kontrol edilmiştir:

apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
  --env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json

İstem, form kodlamasını belirtir çünkü Stripe'ın v1 uç noktaları JSON kabul etmez. livemode doğrulaması sizin tetikleyicinizdir: eğer biri bu senaryoyu canlı bir anahtarla çalıştırırsa, ikinci bir istek gönderilmeden önce başarısız olur. CI'da, aynı apidog run satırı anahtarı ardışık düzeninizin gizli deposundan okur; Apidog CLI CI/CD ardışık düzeni kılavuzumuzda kopyala-yapıştır bir sürüm vardır. İstek tanımı paylaşılır; canlı kimlik bilgisi asla.

Anahtarları döndürme ve bir anahtar sızarsa ne yapılmalı

Stripe'ın kendi anahtar işleme kılavuzu açık sözlüdür: bir depoya işlenen, sohbete yapıştırılan veya bir günlüğe yazdırılan her şeyin tehlikeye girdiğini varsayın, kimsenin görüp görmediğinden emin olmasanız bile.

Döndürme, Kontrol Panosuna yerleştirilmiştir. Bir anahtarın taşma menüsünden Anahtarı döndür'ü seçin, eski anahtar için bir son kullanma tarihi belirleyin ve yenisini kopyalayın. Her ikisi de ek süre boyunca, 7 güne kadar çalışır, böylece kademeli olarak geçiş yapabilir ve geride kalanlar için istek günlüklerini izleyebilirsiniz. Şimdi, eski anahtarı hemen iptal eder.

Bir gizli veya kısıtlı anahtar sızarsa:

• Kısa bir son kullanma süresiyle hemen döndürün.
• Onu kullanan her sunucuyu güncelleyin, istek günlüklerinde trafiği doğrulayın, ardından eski anahtarın süresinin dolmasına izin verin.
• Workbench'teki son etkinliği, entegrasyonunuzun yapmayacağı herhangi bir şey için gözden geçirin: tanınmayan bağlı hesaplar, başlatmadığınız ödemeler, yeni banka hesapları.
• Şüpheli ödemeleri duraklatın, halihazırda gönderilmiş olanları geri çevirin ve itirazları önlemek için sahte ücretleri hızla iade edin.
• Diğer anahtarlarınızı da döndürün. Bir anahtar sızdıysa, onu sızdıran kanalın daha fazlasını gördüğünü varsayın.

Stripe, açığa çıkan anahtarları tarar ve sizi bilgilendirir, bazen anahtarı proaktif olarak devre dışı bırakır, ancak algılama garanti değildir. Depolarınızda ve CI yapılandırmanızda sk_live_ ve rk_live_ aramak beş dakikalık bir denetimdir ve bir ön işleme kancasındaki gizli tarayıcı bir sonrakinin yerleşmesini durdurur. Stripe asla gizli anahtarınızı istemez, bu nedenle onu isteyen herhangi bir mesaj kimlik avıdır.

Yaygın Stripe API anahtarı hataları

401 ve 403 durumları, Python SDK'da stripe.AuthenticationError ve stripe.PermissionError ile eşleşir, hatalar referansına göre, böylece onları özel olarak yakalayabilirsiniz. Daha az belirgin bir durum: 180 gündür transfer veya ödeme oluşturmamış bir canlı anahtar, bu işlemler için sınırlandırılır ve anahtarda bir Erişimi geri yükle seçeneği bulunur.

SSS

Stripe yayınlanabilir anahtarını ön uç koduma koymak güvenli mi?

Evet. Bir pk_ anahtarı kart bilgilerini token'laştırır ancak ödeme oluşturamaz, müşterileri okuyamaz veya para taşıyamaz. Yalnızca gizli ve kısıtlı anahtarlar sunucu tarafında kalır.

Test modunda kısıtlı anahtar kullanabilir miyim?

Evet. Kısıtlı anahtarlar her iki modda da mevcuttur (rk_test_ ve rk_live_). Stripe, önce test sürümünü ayarlamanızı, ardından eşleşen izinlerle bir canlı anahtar oluşturmanızı önerir.

Webhook imzalama sırrı API anahtarım ile aynı mı?

Hayır. İmzalama sırları webhook uç noktası başına verilir ve yalnızca gelen bir olayın Stripe'tan geldiğini doğrular. Webhooks altında bulunurlar, API anahtarları sayfasında değil. Bunları bağlıyorsanız, CI'da Stripe webhook'larını nasıl test edeceğinizi görün.

Üretimde bir test anahtarı kullanırsam ne olur?

İstekler başarılı olur ancak hiçbir kart ücretlendirilmez ve hiçbir para hareket etmez. Her nesnede livemode false döndüğü için, bu alan üzerindeki bir doğrulama hatayı müşterilerden önce yakalar.

Kısa özet

Yayınlanabilir anahtarlar istemciye gider, gizli ve kısıtlı anahtarlar sunucuda kalır, test ve canlı asla karışmaz ve kısıtlı, kapsamını belirleyebildiğiniz her durumda gizliyi yener. Canlı anahtarı bir kasada saklayın, test anahtarını çalışma zamanında Apidog CLI'ye iletin ve ajanınızın yazdığı her test senaryosunda bir livemode doğrulaması bulundurun.