Penjelasan Kunci API Stripe: Test vs Live, Publishable vs Secret, dan Restricted Keys

Setiap integrasi Stripe dimulai dengan pertanyaan yang sama: kunci mana yang dipakai di mana? Stripe memberi Anda publishable key, secret key, dan opsi untuk membuat restricted key, masing-masing dalam varian test dan live. Salah menempatkan kunci di tempat yang keliru, Anda bisa membocorkan kemampuan memindahkan uang atau kehilangan waktu seharian karena error 401. Panduan ini membahas apa fungsi setiap Stripe API key, di mana ia disimpan, cara mengirim permintaan test-mode pertama, dan cara menjaga kunci live agar tidak masuk ke apa pun yang dibagikan. Untuk konsep umumnya terlebih dahulu, mulai dari apa itu API key. Semua yang ada di bawah ini mengikuti dokumentasi API keys Stripe, yang diperiksa pada September 2026.

Di mana Stripe API key Anda berada di Dashboard

Buka halaman API keys di dashboard.stripe.com/apikeys. Halaman ini berada di bawah Developers di Dashboard dan menampilkan kunci untuk akun atau sandbox mana pun yang sedang Anda lihat. Sebuah toggle beralih antara sandbox mode dan live mode, dan daftar kunci ikut berubah.

Halaman ini memiliki dua daftar:

• Standard keys berisi publishable key dan secret key Anda.
• Restricted keys berisi kunci apa pun yang telah Anda buat dengan izin yang dibatasi (scoped permissions).

Visibilitasnya berbeda menurut mode. Di sandbox, Anda dapat menampilkan setiap kunci kapan saja. Di live mode, secret key yang Anda buat sendiri hanya ditampilkan sekali, saat pembuatannya. Salin ke vault Anda sebelum menutup dialog; jika hilang, Anda harus merotasinya. Hanya kunci default yang dihasilkan Stripe yang dapat ditampilkan lagi di live mode.

Satu hal yang tidak ditampilkan halaman ini: webhook signing secret. Itu berada di bawah Webhooks, per endpoint, dan sama sekali bukan API key.

Publishable vs secret key

Namanya menggambarkan batas kepercayaan.

Publishable key digunakan di browser atau aplikasi mobile. Fungsinya mengubah nomor kartu menjadi token dan hampir tidak lebih dari itu. Ia tidak bisa membuat charge atau membaca data akun, jadi menaruhnya di kode front-end adalah hal yang wajar.

Secret key digunakan di server Anda dan tidak di tempat lain. Panduan Stripe telah bergeser: dokumentasinya sekarang menyatakan mereka "tidak merekomendasikan penggunaan secret key untuk kasus penggunaan baru" dan mengarahkan ke restricted key. Secret key tanpa batasan masih berfungsi, tetapi perlakukan ia sebagai opsi darurat, bukan default.

Kunci test vs live mode

Stripe menjalankan dua dunia terpisah, masing-masing dengan set kuncinya sendiri. Kunci test (dokumentasi terbaru menyebut sisi test sebagai sandbox, meskipun prefix-nya masih _test_) mengembalikan objek simulasi: pelanggan palsu, PaymentIntent palsu, kartu test yang berhasil atau ditolak sesuai perintah, tanpa uang nyata. Kunci live terhubung ke jaringan kartu dan memindahkan dana nyata.

Pemisahannya ketat. Pelanggan yang dibuat dengan sk_test_ tidak ada bagi sk_live_, dan sebaliknya. Kode error Stripe untuk mencampuradukkan keduanya, livemode_mismatch, menyatakannya dengan gamblang: "Test and live mode API keys, requests, and objects are only available within the corresponding mode."

Ada dua aturan praktis yang mengikutinya:

• Bangun dan uji sepenuhnya terhadap sk_test_ atau rk_test_. Stripe merekomendasikan sandbox umum terpisah untuk integrasi baru agar pengaturan dan datanya tetap terisolasi.
• Beralih ke live adalah perubahan konfigurasi, bukan perubahan kode. Server Anda membaca kunci dari environment variable atau vault, dan untuk go live berarti mengubah nilai tersebut.

Setiap respons API menyertakan boolean livemode. Buat assertion terhadapnya di test Anda; ini adalah pengaman termurah terhadap deploy dengan kunci yang salah.

Restricted key dan least privilege

Restricted API key (Stripe menyingkatnya RAK) adalah secret key dengan mask izin. Saat Anda membuatnya, Anda memilih izin untuk setiap grup resource: None, Read, atau Write. Semuanya default ke None. Write mencakup Read, dan pemetaannya ke HTTP sederhana: GET membutuhkan Read, POST dan DELETE membutuhkan Write.

Untuk membuatnya, klik Create restricted key di halaman API keys, pilih set izin yang sudah dikonfigurasi sebelumnya atau mulai dari nol, beri nama, atur izin, dan selesaikan prompt two-factor. Seperti halnya secret key yang Anda buat sendiri di live mode, Anda hanya melihat nilainya sekali.

Panduan restricted keys menyarankan satu kunci per layanan: layanan billing mendapat Write pada Invoices dan Customers, tugas pelaporan mendapat Read pada Charges dan Disputes. Jika satu layanan dikompromikan, penyerang terkunci pada izin kunci tersebut. Kunci disputes yang read-only tidak bisa membuat charge atau menyentuh payout.

Berikan izin luas pada kunci baru di sandbox, jalankan test suite Anda, lalu buka request log kunci tersebut (menu overflow, View request logs) dan pangkas setiap izin yang tidak menerima trafik. Stripe juga memungkinkan Anda menandai kunci yang ditujukan untuk agen AI otonom agar tunduk pada aturan persetujuan untuk payout dan refund; gunakan jalur itu alih-alih secret key biasa.

Permintaan pertama Anda dengan curl dan Python

Stripe mengautentikasi dengan HTTP Basic Auth: kuncinya adalah username dan password-nya kosong. Tanda titik dua di akhir memberi tahu curl agar tidak meminta input:

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"

Responsnya adalah PaymentIntent dengan id yang diawali pi_, status: "requires_payment_method", dan livemode: false. Field terakhir itu memastikan Anda menggunakan kunci test.

Stripe juga menerima -H "Authorization: Bearer $STRIPE_API_KEY", yang merupakan bentuk yang digunakan Apidog dan sebagian besar klien HTTP. Keduanya membawa kunci yang sama; jika Anda tidak yakin gaya mana yang cocok dengan stack Anda, perbandingan kami tentang API key dan bearer token membahas untung-ruginya. Permintaan harus melalui HTTPS; HTTP biasa langsung gagal, sesuai referensi autentikasi.

Di Python, pola SDK saat ini adalah StripeClient yang membaca kunci dari environment:

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

Tidak ada string kunci yang muncul di file. Kode yang sama berjalan terhadap test atau live tergantung apa yang disediakan environment.

Biarkan coding agent Anda menguji kunci Stripe dengan Apidog CLI

Curl membuktikan kunci berfungsi sekali. Coding agent Anda dapat mengubahnya menjadi pemeriksaan yang dapat diulang melalui Apidog CLI dan menjaga kunci tetap di luar proyek yang dibagikan. Siapkan sekali (token ada di bawah Account Settings, API Access Token):

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

Lalu berikan satu prompt kepada agent:

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.

Perintah yang dijalankannya, diperiksa terhadap Apidog CLI 2.2.7:

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

Prompt itu menyebut pengodean form karena endpoint v1 Stripe tidak menerima JSON. Assertion livemode adalah jebakan Anda: jika ada yang menjalankan test case dengan kunci live, itu akan gagal sebelum permintaan kedua terkirim. Di CI, baris apidog run yang sama membaca kunci dari secret store pipeline Anda; panduan Apidog CLI CI/CD pipeline kami punya versi yang bisa langsung disalin-tempel. Definisi permintaannya dibagikan; kredensial live-nya tidak pernah.

Merotasi kunci dan apa yang harus dilakukan jika ada yang bocor

Panduan penanganan kunci Stripe sendiri blak-blakan: anggap apa pun yang di-commit ke repo, ditempel di chat, atau tercetak di log sebagai sudah dikompromikan, bahkan jika Anda tidak yakin ada yang melihatnya.

Rotasi sudah terpasang di Dashboard. Dari menu overflow sebuah kunci, pilih Rotate key, atur masa berlaku untuk kunci lama, dan salin penggantinya. Keduanya berfungsi selama masa tenggang, hingga 7 hari, sehingga Anda dapat meluncurkannya secara bertahap dan memantau request log untuk yang tertinggal. Now mencabut kunci lama seketika.

Jika secret atau restricted key bocor:

• Rotasi segera dengan masa berlaku yang singkat.
• Perbarui setiap server yang menggunakannya, konfirmasi trafik di request log, lalu biarkan kunci lama kedaluwarsa.
• Tinjau aktivitas terbaru di Workbench untuk apa pun yang tidak akan dilakukan integrasi Anda: connected account yang tidak dikenal, payout yang tidak Anda inisiasi, rekening bank baru.
• Jeda payout yang mencurigakan, balikkan yang sudah terlanjur terkirim, dan kembalikan charge palsu dengan cepat untuk mencegah sengketa.
• Rotasi juga kunci Anda yang lain. Jika satu bocor, anggap saluran yang membocorkannya telah melihat lebih banyak.

Stripe memindai kunci yang terekspos dan akan memberi tahu Anda, kadang menonaktifkan kunci tersebut secara proaktif, tetapi deteksinya tidak dijamin. Menelusuri repo dan konfigurasi CI Anda untuk sk_live_ dan rk_live_ adalah audit lima menit, dan secret scanner di pre-commit hook menghentikan kebocoran berikutnya. Stripe tidak pernah meminta secret key Anda, jadi pesan apa pun yang memintanya adalah phishing.

Error Stripe API key yang umum

Kasus 401 dan 403 dipetakan ke stripe.AuthenticationError dan stripe.PermissionError di SDK Python, sesuai referensi error, sehingga Anda dapat menangkapnya secara spesifik. Satu kasus yang kurang jelas: kunci live yang belum membuat transfer atau payout selama 180 hari akan dibatasi untuk tindakan tersebut, dengan opsi Restore access pada kunci.

FAQ

Apakah aman menaruh Stripe publishable key di kode frontend saya?

Ya. Kunci pk_ mentokenkan detail kartu tetapi tidak bisa membuat charge, membaca pelanggan, atau memindahkan uang. Hanya secret dan restricted key yang tetap di sisi server.

Bisakah saya menggunakan restricted key di test mode?

Ya. Restricted key ada di kedua mode (rk_test_ dan rk_live_). Stripe merekomendasikan menyetel versi test terlebih dahulu, lalu membuat kunci live dengan izin yang sesuai.

Apakah webhook signing secret sama dengan API key saya?

Tidak. Signing secret diterbitkan per endpoint webhook dan hanya memverifikasi bahwa event yang masuk berasal dari Stripe. Itu berada di bawah Webhooks, bukan halaman API keys. Jika Anda sedang menyiapkannya, lihat cara menguji Stripe webhook di CI.

Apa yang terjadi jika saya menggunakan kunci test di produksi?

Permintaan berhasil tetapi tidak ada kartu yang ditagih dan tidak ada uang yang berpindah. Karena livemode kembali sebagai false pada setiap objek, assertion pada field itu menangkap kesalahannya sebelum pelanggan Anda.

Versi singkatnya

Publishable key masuk ke klien, secret dan restricted key tetap di server, test dan live tidak pernah dicampur, dan restricted lebih baik daripada secret kapan pun Anda bisa membatasinya. Simpan kunci live di vault, berikan kunci test ke Apidog CLI saat runtime, dan pertahankan assertion livemode di setiap test case yang ditulis agent Anda.