Buat API key di Pengembang, Kunci API, satu key per layanan dengan akses dan masa berlaku sendiri. Simpan key di sisi server dan rotasi tanpa downtime.
Pengembang → Kunci API, dibatasi pada aplikasi yang sedang Anda pilih. Setiap aplikasi memiliki key Utama, dan Anda bisa membuat lebih banyak, satu per layanan, masing-masing dengan akses dan masa berlakunya sendiri. Sebuah key adalah secret sisi server: jangan pernah letakkan di kode frontend atau di dalam bundel aplikasi.
API key Anda berada di Pengembang → Kunci API pada konsol, dibatasi pada aplikasi tempat Anda sedang bekerja. Perlakukan setiap key seperti password: key memberikan akses API atas nama aplikasi tersebut.
#Menemukan key Anda
- Masuk ke Konsol Bisnis
Buka business.didit.me dan masuk.
- Pilih aplikasi Anda
Pilih aplikasi dari kartu aplikasi di bagian atas sidebar. Setiap aplikasi punya key-nya sendiri.
- Buka Pengembang, lalu Kunci API
Tab Kunci mencantumkan setiap key, dimulai dari key Utama, beserta aksesnya, kapan terakhir digunakan, dan kapan kedaluwarsa.
#Membuat key
Beri setiap layanan yang memanggil Didit key-nya sendiri, sehingga Anda bisa melihat apa yang dilakukan masing-masing dan mencabutnya secara terpisah.
- Tekan Buat key
Di Pengembang → Kunci API.
- Beri nama dan pilih environment
Namai key sesuai layanan yang akan menggunakannya, pilih Live (verifikasi nyata, ditagih) atau Sandbox (data uji, tidak pernah ditagih; key dibuat di aplikasi Sandbox organisasi Anda), lalu pilih kapan key kedaluwarsa: tidak pernah, setelah 30 hari, 90 hari, atau satu tahun, atau pada tanggal yang Anda pilih.
- Pilih aksesnya
Akses penuh membaca dan menulis semuanya, untuk backend Anda sendiri. Hanya baca melihat session, keputusan, dan media tetapi tidak bisa mengubah apa pun, untuk mitra yang hanya membutuhkan hasil. Kustom memungkinkan Anda memilih, resource demi resource. Hapus centang Sertakan media jika layanan hanya membutuhkan keputusan, bukan gambar ID, selfie, video, atau laporan PDF.
- Tinjau dan salin secret-nya
Secret lengkap hanya ditampilkan sekali, saat key dibuat. Salin langsung ke secret manager Anda.
Key Utama adalah secret asli aplikasi. Key ini selalu memiliki akses penuh dan dapat dirotasi tetapi tidak dapat dicabut.
#API key dan signing secret adalah dua hal yang berbeda
Perlu ditegaskan, karena mencampuradukkan keduanya menghasilkan error yang membingungkan:
| Fungsinya | Di mana | |
|---|---|---|
| API key | Mengautentikasi panggilan Anda ke Didit, di header x-api-key | Per aplikasi, sebanyak yang Anda butuhkan |
| Webhook signing secret | Memverifikasi bahwa webhook yang masuk benar-benar berasal dari Didit | Per endpoint webhook |
Mengirim signing secret sebagai API key Anda menghasilkan error 401. Memverifikasi webhook dengan API key Anda menghasilkan signature yang tidak cocok. Keduanya sering terjadi.
API key Anda adalah secret. Jangan pernah meletakkannya di kode frontend, repositori publik, atau bundel aplikasi mobile - simpan hanya di sisi server. Key di dalam bundel aplikasi yang sudah dirilis adalah key yang sudah dimiliki penyerang. Lihat autentikasi API.
#Mendapatkan key untuk pengujian
Anda tidak menguji terhadap production. Alihkan konsol ke Sandbox dan buat key di sana, atau pilih Sandbox sebagai environment saat Anda membuat key. Session sandbox mensimulasikan setiap pemeriksaan eksternal, tidak pernah ditagih, dan tidak menyentuh data pengguna sungguhan.
Sebuah key dimiliki oleh satu aplikasi, dan dengan begitu juga oleh environment aplikasi tersebut: key sandbox tidak pernah membuat verifikasi live, dan key live tidak pernah membuat verifikasi sandbox. Ada baiknya menamai key Anda secara jelas di mana pun Anda menyimpan secret. Lihat menguji di sandbox.
#Merotasi key Anda
Jika sebuah key mungkin sudah terekspos, buka key tersebut dan pilih Putar key. Anda mendapatkan secret baru, dan secret lama tetap berfungsi selama 24 jam, sehingga Anda bisa men-deploy secret baru tanpa downtime. Setelah itu, setiap permintaan dengan secret lama mengembalikan 401.
Jika sebuah key harus berhenti berfungsi saat ini juga, gunakan Cabut key. Pencabutan menghentikannya seketika dan tidak bisa dibatalkan. Key Utama hanya bisa dirotasi.
Merotasi secara terjadwal adalah praktik yang baik. Rencanakan seperti sebuah deploy, bukan sekadar satu klik.
#Mengatasi error 401 dan 403
| Error | Penyebab | Perbaikan |
|---|---|---|
401 | Key hilang, salah format, kedaluwarsa, dicabut, atau dirotasi lebih dari 24 jam yang lalu | Periksa key di Pengembang → Kunci API untuk aplikasi tersebut. Periksa apakah ada spasi atau tanda kutip yang tidak sengaja terikut, dan pastikan Anda tidak menempelkan signing secret |
403 | Key-nya valid tetapi panggilan ini tidak diizinkan | Biasanya karena aplikasi yang salah, field khusus sandbox pada key live (atau sebaliknya), akses yang tidak diberikan ke key tersebut (misalnya key hanya baca yang mencoba menulis), atau fitur yang belum diaktifkan pada akun Anda |
Error 403 pada workflow tertentu hampir selalu berarti key tersebut milik aplikasi yang berbeda dari aplikasi yang memiliki workflow itu. Pindah aplikasi di konsol dan gunakan salah satu key-nya sebagai gantinya. Rincian lengkap: error API dan artinya.
#Membatasi apa yang bisa dilakukan sebuah key
Pilih aksesnya saat Anda membuat key, dan ubah nanti dengan Ubah akses (secret-nya tetap sama; akses key Utama tidak bisa diubah). Hanya baca mencegah mitra mengubah apa pun, Kustom menetapkan Tidak ada, Baca, atau Tulis per resource (session, keputusan, media, orang, perusahaan, dan lainnya), dan membiarkan Sertakan media nonaktif mencegah sebuah layanan mengunduh gambar ID, selfie, video, dan laporan PDF. Di bawah Batasan, sebuah key juga bisa dibatasi pada workflow tertentu, hanya pada session yang disetujui, atau pada daftar alamat IP: permintaan dari luar daftar dijawab dengan 403, dan session di luar workflow atau status key tersebut dijawab dengan 404. Buka sebuah key untuk melihat dengan tepat apa yang bisa dilakukannya; sebuah key tidak pernah bisa melakukan lebih dari yang diizinkan aksesnya.
#Siapa di tim Anda yang bisa melihat key
Visibilitas key mengikuti peran: melihat halaman ini memerlukan izin untuk membaca API key, yang termasuk dalam peran Pengembang. Secret tetap tersamarkan di konsol. Jika rekan tim tidak bisa menemukan halamannya, periksa dulu perannya sebelum melaporkannya. Lihat mengundang anggota tim dan menetapkan peran.
#Setiap panggilan dicatat
Permintaan dengan API key muncul di Log audit dan diatribusikan ke key tersebut, bukan ke seseorang. Itulah sebabnya key yang dibagikan ke beberapa layanan membuat sebuah insiden lebih sulit diselidiki: satu key per konsumen lebih mudah untuk dipahami. Lihat menggunakan audit log.
Masih buntu? Bicara dengan manusia.
Sertakan ID organisasi Anda dan ID sesi yang Anda tanyakan.