# Kunci API Dibatasi

Gunakan kunci API dibatasi untuk mengontrol akses aplikasi Anda ke API Stripe.

Anda dapat menggunakan kunci API dibatasi (RAK) untuk menetapkan izin API Stripe tertentu pada kunci API Anda. Menggunakan RAK seperti ini membatasi potensi kerugian pada bisnis Anda jika kunci API terekspos kepada pihak yang tidak bertanggung jawab. Jika kunci API dibatasi tidak memiliki izin yang benar untuk menyelesaikan permintaan API, Stripe akan mengembalikan [kesalahan permintaan tidak valid](https://docs.stripe.com/error-handling.md#invalid-request-errors).

## Apa itu kunci API dibatasi?

Ketika Anda mendaftar ke Stripe, Anda mendapatkan [kunci API rahasia](https://docs.stripe.com/keys.md#obtain-api-keys) (dimulai dengan `sk_live_` atau `sk_test_`). Setiap orang, agen, atau sistem yang memiliki kunci rahasia Anda dapat melakukan *apa saja* di akun Stripe Anda: membuat charge, mengeluarkan pengembalian dana, membaca data pelanggan, memicu payout, dan lainnya.

Kunci API dibatasi (RAK) dimulai dengan `rk_live_` atau `rk_test_` dan hanya dapat melakukan hal yang Anda tentukan. Saat Anda membuat RAK di Dashboard Stripe, Anda memilih sumber daya Stripe mana yang dapat diakses oleh kunci tersebut dan izin untuk setiap sumber daya: **Baca**, **Tulis**, atau **Tidak ada**. Semua API Stripe mendukung kunci API dibatasi.

Anda dapat menggunakan kunci dibatasi sebagai langkah defensif untuk melindungi akun Stripe Anda jika kunci Anda terekspos atau disusupi. Jika pihak yang tidak bertanggung jawab mendapatkan kunci API dibatasi, mereka hanya dibatasi oleh izin pada kunci tersebut. Sebagai contoh, Anda dapat membuat kunci dibatasi yang hanya dapat membaca data sengketa dan tidak melakukan hal lain. Jika kunci tersebut diperoleh pihak yang tidak bertanggung jawab, mereka hanya dapat membaca data sengketa. Mereka tidak dapat membuat charge, mengakses metode pembayaran pelanggan, atau memicu payout.

Stripe merekomendasikan untuk selalu menggunakan kunci dibatasi daripada kunci rahasia tanpa batas. Selalu ikuti praktik terbaik saat menggunakan kunci dibatasi untuk menghindari paparan atau penyalahgunaan yang tidak disengaja. Lihat [praktik terbaik untuk mengelola kunci API rahasia](https://docs.stripe.com/keys-best-practices.md).

## Mengapa menggunakan kunci dibatasi dibandingkan kunci rahasia?

|                                 | Kunci rahasia (`sk_`)                                               | Kunci dibatasi (`rk_`)                                                |
| ------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Ruang lingkup akses**         | Akses penuh ke semua sumber daya API                                | Hanya izin yang Anda tetapkan                                         |
| **Dampak jika disusupi**        | Pihak tidak bertanggung jawab dapat melakukan apa saja di akun Anda | Pihak tidak bertanggung jawab hanya dapat melakukan sesuai izin kunci |
| **Berbagi dengan pihak ketiga** | Berbahaya: memberikan kontrol penuh kepada pihak ketiga             | Lebih aman: Anda hanya memberikan akses yang diperlukan               |
| **Prinsip hak akses minimum**   | Tidak dapat diterapkan dengan kunci tanpa batas                     | Anda dapat memberikan izin minimal                                    |
| **Rekomendasi Stripe**          | Gunakan secara dibatasi dan lindungi secara ketat                   | **Direkomendasikan**: Gunakan kunci dibatasi sebisa mungkin           |

### Alasan beralih ke kunci API dibatasi

- **Membatasi dampak jika kunci diambil alih**: Jika kunci dibatasi disusupi, pihak tidak bertanggung jawab hanya dapat mengakses sumber daya tertentu yang Anda izinkan.

- **Berbagi kunci dengan aman kepada pihak ketiga**: Stripe tidak menganjurkan berbagi kunci dalam sebagian besar situasi, tetapi untuk beberapa integrasi pihak ketiga, Anda mungkin perlu membagikan kunci. Misalnya, jika vendor perlu memantau sengketa Anda, berikan kunci dibatasi dengan akses baca saja untuk sengketa, bukan kunci rahasia tanpa batas. Jika Anda bekerja dengan pihak ketiga, pastikan mereka mengikuti [praktik terbaik](https://docs.stripe.com/keys-best-practices.md) untuk menangani kunci dengan aman, seperti menggunakan daftar IP yang diizinkan jika memungkinkan untuk mengurangi risiko penyalahgunaan, dan menonaktifkan kunci jika hubungan kerja berakhir.

- **Memenuhi persyaratan kepatuhan**: Banyak audit keamanan dan kerangka kerja kepatuhan mengharuskan penerapan prinsip hak akses minimum. Kunci dibatasi memudahkan hal ini.

- **Menggabungkan dengan pembatasan IP**: Anda dapat mengunci kunci dibatasi ke sekumpulan alamat IP tertentu untuk lapisan perlindungan tambahan.

## Bermigrasi dari kunci rahasia ke kunci dibatasi

Kunci API dibatasi dapat digunakan sebagai pengganti langsung kunci API rahasia. Untuk menggunakannya, berikan kunci tersebut ke kode Anda dengan cara yang sama seperti kunci rahasia, dengan mengikuti [praktik terbaik](https://docs.stripe.com/keys-best-practices.md) agar tidak terekspos secara tidak sengaja. Semua API Stripe mendukung kunci API dibatasi. Anda perlu mengonfigurasi izin setiap kunci dibatasi untuk mendapatkan manfaatnya.

Berikut adalah pendekatan langkah demi langkah untuk bermigrasi dari kunci rahasia ke kunci dibatasi. Lihat [Menetapkan izin ke kunci API dibatasi](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) untuk memahami cara mengurangi izin kunci dibatasi.

### Tinjau penggunaan API dari kunci rahasia

Tinjau kode Anda dan integrasi pihak ketiga untuk mencatat produk Stripe yang Anda gunakan dan panggilan API yang saat ini dilakukan dengan kunci rahasia.

Tinjau [log permintaan di Workbench](https://dashboard.stripe.com/workbench/logs) dari kunci rahasia. Anda dapat menggunakan tabel di bawah untuk memetakan permintaan API yang berhasil ke izin RAK yang diperlukan.

| Metode HTTP | Jenis izin RAK |
| ----------- | -------------- |
| GET         | baca           |
| POST        | tulis          |
| DELETE      | tulis          |

Sebagai contoh, jika Anda melihat panggilan berhasil ke `GET /v1/customers`, Anda perlu menambahkan izin baca untuk sumber daya [Customer](https://docs.stripe.com/api/customers.md) pada izin RAK pengganti.

### Buat kunci dibatasi di lingkungan sandbox

Stripe merekomendasikan membuat kunci dibatasi di sandbox Stripe sebelum membuat kunci mode live.

1. Buka halaman [kunci API](https://dashboard.stripe.com/apikeys) di Dashboard Stripe.
1. Klik **Buat kunci dibatasi**.
1. Berikan nama deskriptif, seperti `billing-service-test`.
1. Untuk setiap sumber daya, tetapkan izin ke **Tidak ada**, **Baca**, atau **Tulis** berdasarkan penggunaan API yang Anda amati sebelumnya.

### Konfigurasikan lingkungan staging Anda untuk menggunakan kunci dibatasi

Di aplikasi uji atau staging Anda, ganti kunci rahasia dengan kunci dibatasi pada lingkungan server (misalnya dalam variabel lingkungan atau penyimpanan rahasia). SDK Stripe dan panggilan HTTP tetap bekerja sama. Perbedaannya hanya pada nilai kunci.

### Tinjau log permintaan kunci dibatasi untuk kesalahan dan sesuaikan izin

Tinjau log kunci dibatasi dalam mode percobaan dari [daftar kunci](https://dashboard.stripe.com/apikeys) dengan mengklik menu tambahan (⋯) di samping kunci dan memilih **Lihat log permintaan**.

Jika Anda menemukan pesan kesalahan seperti `403 ERR`, edit izin kunci dibatasi untuk menambahkan aksi yang gagal:

1. Klik menu tambahan (⋯) di samping kunci.
1. Pilih **Edit kunci**.
1. Ulangi percobaan Anda di dalam sandbox untuk memastikan bahwa Anda telah menetapkan izin yang benar ke kunci dibatasi.

Periksa log aplikasi Anda untuk kesalahan API Stripe. Jika kunci dibatasi yang digunakan tidak memiliki izin yang sesuai, respons akan menyertakan pesan kesalahan yang menjelaskan izin yang perlu ditambahkan.

### Buat kunci dibatasi mode live

Buat kunci dibatasi baru dalam mode live dengan izin yang sama seperti kunci mode percobaan yang telah Anda uji.

### Konfigurasikan lingkungan produksi untuk menggunakan kunci dibatasi

Gunakan kunci baru di lingkungan produksi dengan cara yang sama seperti pada lingkungan staging.

### Nonaktifkan kunci rahasia lama

Setelah Anda yakin semuanya berjalan dengan baik dalam mode percobaan, [rotasikan](https://docs.stripe.com/keys.md#rolling-keys) atau [hentikan](https://docs.stripe.com/keys.md#delete-secret-key) kunci rahasia lama di Dashboard. Ini memastikan tidak ada yang dapat menggunakannya lagi. Anda dapat mengatur masa kedaluwarsa tertunda (hingga 7 hari) sebagai masa aman jika perlu kembali ke kunci lama.

## Menetapkan izin pada kunci API dibatasi

Anda dapat mengonfigurasi kunci dibatasi sesuai contoh penggunaan Anda spesifik berdasarkan prinsip hak akses minimum: sebuah kunci hanya boleh memiliki izin minimum yang diperlukan untuk menjalankan tugasnya. Berikut beberapa pendekatan praktis:

### Audit log permintaan untuk menentukan izin

1. Buka halaman [Kunci API](https://dashboard.stripe.com/apikeys) di Dashboard.
1. Temukan kunci dibatasi yang ingin dikonfigurasi.
1. Klik menu tambahan (⋯) di samping kunci.
1. Klik **Lihat log permintaan** untuk melihat semua permintaan yang dibuat dengan kunci tersebut.

Tinjau endpoint API yang digunakan aplikasi Anda selama percobaan dengan kunci dibatasi untuk melihat secara tepat sumber daya mana yang digunakan aplikasi Anda dan apakah Anda membaca atau menulis ke sumber daya tersebut:

- Permintaan `GET` adalah baca
- Permintaan `POST` dan `DELETE` adalah tulis

Jika aplikasi Anda berfungsi dengan baik dalam percobaan, buatlah daftar panggilan yang berhasil di dalam log permintaan, lalu bandingkan daftar tersebut dengan izin yang Anda berikan ke kunci dibatasi. Anda dapat menghapus izin apa pun yang tidak digunakan oleh kunci Anda. Untuk mengubah izin kunci:

1. Klik menu tambahan (⋯).
1. Klik **Edit kunci**.

Jika aplikasi Anda tidak berfungsi dengan baik, Anda dapat memfilter log permintaan kunci untuk menampilkan permintaan yang tidak berhasil, lalu ubah izin kunci di menu kunci untuk menambahkan izin Stripe API yang sesuai.

### Tinjau kode Anda

Anda dapat menyusun daftar izin yang diperlukan dengan mencari panggilan Stripe SDK di dalam basis kode Anda. Petakan setiap panggilan ke izin yang sesuai di Dashboard. Sebagai contoh:

- `PaymentIntent.create(...)` → **PaymentIntents: Tulis**
- `Customer.retrieve(...)` → **Customers: Baca**
- `Dispute.list(...)` → **Disputes: Baca**

Kemudian sesuaikan izin kunci dibatasi sesuai kebutuhan tersebut.

### Mulai dengan izin luas lalu kurangi

Anda dapat memberikan izin yang luas kepada kunci dibatasi pada awalnya, lalu hapus izin berlebih setelah meninjau bagaimana kunci tersebut digunakan.

Di dalam sandbox, buat kunci dibatasi dari menu kunci API. Izin yang tersedia dikelompokkan ke dalam beberapa kategori. Jika Anda tahu bahwa penggunaan Stripe API Anda tidak mencakup kategori tertentu, seperti Stripe Billing, Anda dapat memilih **Tidak Ada** untuk kategori tersebut. Jika tidak, pilih **Tulis** untuk kategori yang relevan dengan penggunaan Stripe API Anda. Izin **Tulis** mencakup izin **Baca**: jika sebuah kunci dapat menulis sumber daya API, kunci tersebut juga dapat membaca sumber daya tersebut.

Uji aplikasi Anda dengan kunci dibatasi mode percobaan seperti yang dijelaskan di atas sehingga aplikasi Anda menggunakan kunci tersebut untuk membuat permintaan Stripe API. Uji setiap komponen aplikasi Anda yang menggunakan Stripe API.

## Gunakan satu kunci dibatasi per layanan atau contoh penggunaan

Jika Anda memiliki beberapa layanan yang menggunakan Stripe API (misalnya, layanan penagihan, layanan pelaporan, dan penanganan webhook), buatlah kunci dibatasi yang terpisah untuk setiap layanan, dan berikan setiap kunci hanya izin Stripe API yang dibutuhkan oleh masing-masing layanan. Memberikan izin terpisah memungkinkan Anda untuk membatasi dampak potensial dari pengambilalihan kunci jika salah satu layanan Anda disusupi.