Setiap sistem autentikasi API pada dasarnya menjawab satu pertanyaan: bagaimana server tahu bahwa permintaan yang masuk benar-benar berasal dari pihak yang berhak? Partner API Mutasiku menjawabnya dengan tiga lapisan sekaligus — bukan satu saja — yaitu USERID, SECRET CODE, dan whitelist IP. Artikel ini menjelaskan kenapa tiga lapisan ini dipakai bersamaan, dan apa yang dilindungi masing-masing jika berdiri sendiri.
Tiga lapisan, tiga jenis perlindungan
Cara paling mudah memahami kombinasi ini adalah dengan membaginya ke tiga kategori klasik dalam keamanan sistem: sesuatu yang Anda punya sebagai identitas, sesuatu yang Anda rahasiakan, dan sesuatu tentang dari mana permintaan itu datang.
- USERID — identitas akun, formatnya seperti
C0001. Ini bukan rahasia dalam arti mutlak (mirip seperti username), tapi berfungsi menandai akun mana yang sedang mengakses API. - SECRET CODE — string 64 karakter heksadesimal yang menjadi bukti bahwa pemanggil memang pemilik sah USERID tersebut. Ini adalah lapisan kerahasiaan utama, setara dengan kata sandi.
- Whitelist IP — daftar alamat IP yang diizinkan memanggil API atas nama akun tersebut, minimal satu IP wajib didaftarkan. Ini adalah lapisan berbasis lokasi jaringan, terlepas dari valid atau tidaknya USERID dan SECRET CODE.
Kenapa satu lapisan saja tidak cukup
Bayangkan jika Partner API hanya mengandalkan USERID dan SECRET CODE saja, tanpa whitelist IP. Begitu kombinasi ini bocor — misalnya tersimpan di kode yang tidak sengaja ter-commit ke repository publik — siapa pun di mana pun bisa langsung memanggil API dan membaca seluruh data mutasi akun tersebut. Whitelist IP menutup celah ini: meskipun kredensial bocor, permintaan dari IP yang tidak terdaftar tetap akan ditolak dengan status 403.
Sebaliknya, whitelist IP saja juga tidak cukup. IP address bisa dipalsukan dalam beberapa skenario jaringan, dan yang lebih penting, whitelist IP tidak membedakan siapa di antara pengguna server tersebut yang sebenarnya berhak memanggil API. Di sinilah USERID dan SECRET CODE tetap wajib ada sebagai bukti identitas per akun — whitelist IP membatasi dari mana permintaan boleh datang, sementara USERID dan SECRET CODE membatasi siapa yang boleh mengirim permintaan itu.
Dengan ketiganya digabung, seorang penyerang perlu berhasil di tiga hal sekaligus: mengetahui USERID yang valid, mencuri SECRET CODE yang sesuai, dan mengirim permintaan dari salah satu IP yang sudah terdaftar di whitelist. Menggabungkan tiga syarat ini jauh lebih sulit ditembus dibanding mengandalkan satu syarat saja.
Detail kecil yang sengaja dirancang: pesan error 401 yang identik
Ada satu detail keamanan yang mudah terlewat tapi penting: ketika autentikasi gagal karena USERID tidak dikenal, atau karena USERID benar tapi SECRET CODE salah, Partner API Mutasiku sengaja mengembalikan pesan 401 yang identik persis di kedua kasus — "USERID atau SECRET CODE tidak valid."
Ini bukan keterbatasan sistem, melainkan keputusan desain yang disengaja. Jika pesan errornya berbeda — misalnya “USERID tidak ditemukan” versus “SECRET CODE salah” — seorang penyerang yang mencoba menebak-nebak kredensial bisa memakai perbedaan pesan itu untuk mengetahui bagian mana yang sudah benar. Dengan menyamakan pesannya, sistem tidak membocorkan informasi parsial yang bisa dimanfaatkan untuk mempersempit tebakan.
Prinsip “jangan membocorkan informasi parsial lewat pesan error” ini umum dipakai dalam sistem login di banyak aplikasi, bukan hanya di Partner API. Pola yang sama juga berlaku pada mekanisme penguncian akun atau pembatasan IP di banyak sistem otentikasi modern.
Apa yang dilindungi masing-masing lapisan
| Lapisan | Melindungi dari | Kelemahan jika berdiri sendiri |
|---|---|---|
| USERID | Memastikan permintaan ditujukan pada akun yang benar | Bukan rahasia, mudah diketahui atau ditebak formatnya |
| SECRET CODE | Pemalsuan identitas oleh pihak yang tidak tahu rahasia akun | Jika bocor dan tidak ada whitelist IP, bisa dipakai dari mana saja |
| Whitelist IP | Penggunaan kredensial yang bocor dari lokasi tidak dikenal | Tidak membedakan siapa di antara pengguna IP tersebut yang sah |
| Pesan 401 identik | Upaya menebak kredensial dengan memanfaatkan perbedaan pesan error | Tidak relevan jika tidak dikombinasikan dengan rate limit |
Partner API juga membatasi 60 permintaan per menit per IP dan mencatat setiap panggilan — berhasil maupun gagal — di Setting > API Activity pada dashboard. Kombinasi rate limit dan log aktivitas ini melengkapi tiga lapisan di atas: meskipun seseorang mencoba menebak kredensial secara berulang, upaya itu akan dibatasi kecepatannya dan tetap tercatat untuk ditinjau. Untuk panduan integrasi lengkap, baca panduan integrasi Partner API Mutasiku untuk developer.
Memahami kenapa tiga lapisan ini dipakai bersamaan membantu developer memperlakukan kredensial API dengan cara yang tepat — SECRET CODE dijaga serahasia kata sandi, whitelist IP diperbarui setiap kali infrastruktur server berubah, dan log aktivitas dipantau secara rutin, bukan hanya ketika ada masalah.