Agent SDK Rahasia & HMAC Penandatanganan
Lindungi kredensial Agen API dan pahami bagaimana SDK menghasilkan tanda tangan permintaan HMAC-SHA256 yang diberi stempel waktu dan tahan pemutaran ulang.
Agent SDK permintaan diautentikasi dengan rahasia API mitra. Jaga rahasia itu di dalam layanan backend tepercaya dan biarkan SDK menghasilkan kolom penandatanganan bila memungkinkan.
Dua protokol penandatanganan
Penandatanganan Agent SDK menggunakan bidang permintaan yang diurutkan, stempel waktu berbasis detik, dan nonce. Permintaan langsung Developer API menggunakan proses terpisah yang dijelaskan dalam Permintaan Penandatanganan. Jangan menggunakan kembali satu format muatan untuk format muatan lainnya.
Aturan penandatanganan
Untuk permintaan Agent SDK:
- Kecualikan bidang
sign. - Hilangkan bidang dengan nilai kosong.
- Urutkan nama bidang yang tersisa dalam urutan ASCII.
- Bergabunglah dengan bidang sebagai
k=v&k2=v2. - Hitung tanda tangan heksadesimal HMAC-SHA256 dengan
apiSecret.
Nilai array diserialkan sebagai kompak JSON sebelum bergabung dengan payload penandatanganan. Misalnya, platformUserIds ditandai sebagai ["1188041528"], memberikan platformUserIds=["1188041528"] dalam payload k=v. Pertahankan urutan elemen array, tanda kutip ganda, dan ID string; jangan menyisipkan spasi pemformatan atau menggunakan Java List.toString() (seperti [1188041528]). SDK menangani serialisasi ini secara otomatis.
SDK harus membangun nilai ini dari data yang sama yang dikirimkannya. Mengubah bidang yang ditandatangani setelah pembuatan tanda tangan menyebabkan verifikasi gagal.
SDK-bidang yang dikelola
Penyimpanan rahasia
- Muat
apiSecretdari pengelola rahasia backend atau konfigurasi runtime yang dilindungi. - Jangan pernah menempatkan rahasia di bundel frontend, aplikasi seluler, klien desktop, tangkapan layar, atau tiket dukungan.
- Pisahkan kredensial untuk pengembangan, pementasan, dan produksi.
- Batasi akses ke layanan dan operator yang memerlukannya.
- Redaksikan tanda tangan permintaan, nilai otorisasi, dan rahasia dari log.
- Cabut dan ganti kredensial jika diduga ada paparan.
Perlindungan jam dan pemutaran ulang
SDK mencakup timestamp dan nonce untuk mengurangi risiko pemutaran ulang. Jaga sinkronisasi jam backend dan jangan gunakan kembali nonce yang dibuat secara manual. Jika validasi tanda tangan gagal, konfirmasikan rahasia yang dikonfigurasi, waktu server, bidang serial, dan lingkungan sebelum mencoba lagi.