Keamanan

Otorisasi hanya melalui kunci

Kontrak mendefinisikan tepat dua skema keamanan, dan keduanya membawa rahasia yang sama:

Skema	Header	Catatan
ApiKeyHeader	X-API-Key	Direkomendasikan.
BearerAuth	Authorization: Bearer	Setara. Gunakan saat pustaka klien mengharuskan bearer token.

Kedua bentuk menghasilkan kredensial yang sama. GET /v1/products adalah satu-satunya endpoint yang menerima panggilan tanpa autentikasi.

Tidak ada allowlist IP. Batas laju per IP adalah plafon yang dipakai bersama oleh semua yang berada di balik satu alamat — batas ini membatasi penyalahgunaan, bukan memberikan atau menolak akses. Perlakukan kunci sebagai keseluruhan batas otoritas untuk akun Anda.

Kunci

Kunci API Zelnum adalah ck_ diikuti 48 karakter: totalnya 51. Apa pun yang lebih pendek bukan kunci, sebuah pemeriksaan yang berguna saat secret manager merusak sebuah nilai.

Lakukan	Jangan
Simpan di secret manager atau variabel lingkungan	Menaruhnya di repositori, berkas konfigurasi yang dapat dibaca pengguna, atau log CI
Kirim dari server Anda	Menaruhnya di JavaScript browser, bundel aplikasi seluler, atau klien publik apa pun
Baca api_key_id saat Anda perlu mengidentifikasi kunci	Menempelkan kunci itu sendiri ke permintaan dukungan
Samarkan di log	Mencatat header permintaan secara lengkap

Kunci di dalam bundel front-end bukanlah rahasia. Jika sebuah integrasi perlu memanggil API dari browser, browser harus memanggil server Anda sendiri dan server Anda yang memegang kunci — plafon per IP untuk lalu lintas yang tampak tanpa autentikasi tidak akan menyelamatkan Anda.

Basis data menyimpan hash SHA-256 dan prefiks tampilan 9 karakter, tidak pernah nilainya sendiri, sehingga dump yang bocor tidak memberikan token yang dapat dipakai kepada siapa pun. Sisi lainnya adalah tidak ada endpoint yang dapat mengembalikan kunci Anda: jika Anda kehilangannya, Anda harus merotasi.

Pastikan kunci mana yang aktif

curl -X GET "https://api.zelnum.com/api/v1/api-key" \
  -H "X-API-Key: YOUR_KEY_HERE"

Respons membawa api_key_id, masked_key, last_used dan created_at — untuk kunci aktif yang paling baru diterbitkan pada akun. Endpoint ini melaporkan satu kunci, jadi bacalah sebagai “kunci yang sedang saya gunakan saat ini”, bukan sebagai inventaris. Untuk melihat semua kunci, gunakan Konsol.

last_used adalah cara tercepat untuk memastikan rotasi berhasil, dengan satu catatan: nilainya ditulis paling banyak sekali setiap lima menit per kunci, sehingga kunci yang sering dipakai masih dapat terbaca belum tersentuh hingga lima menit setelah Anda beralih ke kunci itu. Jangan menyimpulkan bahwa deployment rusak hanya dari last_used yang basi.

Merotasi kunci

Sebuah akun dapat menyimpan beberapa kunci aktif sekaligus, dan Konsol mengelolanya satu per satu:

Tindakan di Konsol	Efek
Buat	Menambahkan kunci. Semua kunci yang ada tetap berfungsi.
Regenerasi	Menonaktifkan kunci itu dan menerbitkan pengganti dengan nama yang sama. Kunci asli langsung berhenti berfungsi.
Hapus	Menghapus kunci sepenuhnya.

Itu memberi Anda dua bentuk rotasi, dan pilihannya bergantung pada apakah Anda mampu menyediakan jendela tumpang tindih.

Buat kunci kedua — rotasi bertahap, dan yang sebaiknya dipilih:

1. Buat kunci baru di Konsol. Tidak ada hal lain yang berubah; kunci lama masih terautentikasi.
2. Siapkan nilai baru di semua tempat yang memerlukannya — server aplikasi, worker, cron job, skrip terjadwal — tanpa mengaktifkannya dulu.
3. Alihkan deployment. Verifikasi dengan GET /v1/api-key sampai melaporkan api_key_id yang baru, dengan memperhitungkan granularitas last_used lima menit.
4. Hapus kunci lama setelah tidak ada lagi yang memanggil dengannya. Inilah langkah yang benar-benar menghapus kredensial — rotasi belum selesai sampai langkah ini dilakukan.

Regenerasi di tempat — saat nilai lama harus segera dimatikan:

Gunakan ini saat kunci telah terekspos dan validitas lanjutannya menjadi risiko.

1. Terima celah waktunya. Kunci lama berhenti berfungsi seketika Anda meregenerasi, sehingga setiap komponen yang masih memegangnya mengembalikan 401 unauthorized sampai di-deploy ulang. Tidak ada tumpang tindih, memang demikian rancangannya.
2. Regenerasi di Konsol dan segera salin nilai teks polos dari banner — nilai itu ditampilkan di sana dan tidak di tempat lain, selamanya.
3. Deploy nilai baru, lalu pastikan tidak ada lagi yang mencatat 401 ke log.

Nilai teks polos hanya ditampilkan sekali

Nilai teks polos sebuah kunci hanya muncul pada saat kunci dibuat atau diregenerasi dan tidak pernah dapat diambil lagi setelahnya. Jika Anda kehilangannya sebelum sampai ke penyimpanan rahasia Anda, lakukan rotasi lagi.

Transport

Setiap endpoint menggunakan HTTPS. Tidak ada listener teks polos, dan tidak ada endpoint yang menerima penurunan versi, sehingga tidak ada konfigurasi yang membuat kunci berjalan tanpa enkripsi.

Jika Anda membangun proxy atau gateway di depan API, akhiri TLS di tepi dan teruskan header X-API-Key — jangan menulis ulang header itu, dan jangan menambahkannya ke log permintaan masuk.

Apa yang Anda kirim, dan berapa lama disimpan

Masukan API adalah nomor telepon dan alamat email — data pribadi di sebagian besar yurisdiksi. Dua konsekuensinya:

• Kirim hanya yang Anda butuhkan. Sebuah pemeriksaan hanya memerlukan pengenal dan tidak yang lain. Jangan menambahkan user id, referensi internal, atau metadata teks bebas ke body permintaan: itu tidak disimpan sebagai field, hanya memperluas eksposur log Anda sendiri.
• Ketahui jendela retensinya. Log realtime dan hasil pemutaran ulang idempotensi disimpan 30 hari secara default, dan berkas hasil massal 7 hari (result_retention_days). Setelah jendela tersebut catatannya hilang, jadi ekspor apa pun yang wajib Anda simpan.

Perlakukan nomor itu sebagai data sensitif di sistem Anda sendiri juga. Hasil deteksi memberi tahu pengamat apakah seseorang tertentu terdaftar di platform tertentu, dan pasangan pengenal dan putusan lebih mengungkap daripada salah satu bagiannya saja.

Melindungi diri dari penagihan ganda

Ini sama-sama sifat keamanan maupun penagihan: Idempotency-Key membuat percobaan ulang aman, sehingga gangguan jaringan atau operator yang tidak sabar tidak dapat mengubah satu tagihan menjadi dua. Jangan pernah membuat kunci baru untuk mencoba ulang permintaan yang hasilnya tidak Anda amati — lihat Idempotensi & Percobaan Ulang.

Berikutnya

• Status & Dukungan — apa yang perlu disertakan saat Anda mengeskalasi, tanpa membocorkan kunci
• Kode Kesalahan — unauthorized dan account_banned dalam konteksnya