Autentikasi, Otorisasi & All-in-One API Key
Platform DagangBot menerapkan arsitektur keamanan berlapis (Zero Trust) yang memisahkan akses pengguna manusia (dashboard) dan akses mesin (integrasi eksternal). Autentikasi ganda ini memadukan JSON Web Token (JWT) untuk sesi interaktif dan All-in-One API Key (dgb_all_) untuk mikrolayanan terisolasi dengan kontrol akses granuler.
1. Ikhtisar & Nilai Bisnis
Keamanan platform tidak hanya berfokus pada pencegahan akses tidak sah, tetapi juga pada pembatasan radius dampak (blast radius) jika terjadi kebocoran kredensial. Pendekatan autentikasi DagangBot memberikan perlindungan tingkat korporat untuk data operasional merchant.
- Autentikasi Sesi Manusia (JWT): Sesi dashboard diamankan menggunakan token JWT berusia pendek yang diperbarui menggunakan mekanisme Refresh Token. Ini memastikan bahwa akses dari browser dapat dipantau dan diakhiri kapan saja, tanpa meninggalkan kredensial permanen di perangkat pengguna.
- Otorisasi Mesin-ke-Mesin (API Key): Integrasi sistem eksternal difasilitasi melalui All-in-One API Key. Kunci ini dirancang untuk komunikasi tanpa intervensi manusia, ideal untuk skrip sinkronisasi, sistem ERP, dan webhook.
- Isolasi Multi-Tenant (RLS): Setiap token dan kunci API secara intrinsik terikat pada pengenal merchant tertentu. Di lapisan database PostgreSQL, Row Level Security (RLS) menjamin bahwa kueri secara otomatis dibatasi pada data milik tenant tersebut, menghilangkan risiko kebocoran data lintas akun (BOLA/IDOR).
- Pembatasan Scope (Least Privilege): Pengembang dapat membatasi kunci API hanya pada kapabilitas yang dibutuhkan (misalnya, hanya membaca katalog produk tanpa izin membuat pesanan).
- Pencabutan Kunci Instan: Validasi token dilakukan melalui lapisan cache Redis yang beroperasi pada latensi sub-milidetik. Jika kunci dicabut melalui dashboard, invalidasi terjadi seketika di seluruh klaster server.
Untuk mencegah penyalahgunaan, DagangBot menerapkan isolasi rute secara ketat. Kunci dgb_all_ hanya berlaku di ekosistem rute /api/v1/all-in-one/*. Sebaliknya, rute aplikasi dashboard tradisional menolak kunci ini dan akan mengembalikan 403 Forbidden.
2. Alur Visual & Antarmuka
Manajemen siklus hidup API Key sepenuhnya dilakukan melalui antarmuka Portal Pengembang di dalam Dashboard DagangBot (/app/integrations). Antarmuka ini dirancang untuk mencegah eksposur rahasia yang tidak disengaja serta mengamankan akses melalui proteksi IP allowlist:


3. Panduan Langkah-demi-Langkah
Integrasi membutuhkan pemahaman mendalam tentang siklus otentikasi. Bagian ini merinci langkah pendaftaran akun dan penggunaan API Key.
Langkah 1: Registrasi Akun dan Verifikasi OTP
Pendaftaran akun baru di platform DagangBot membutuhkan validasi nomor telepon melalui OTP (One-Time Password) yang dikirimkan via WhatsApp.
/auth/registerPublikRegister merchant and trigger OTP
Body (wajib)
Respons
/auth/verify-otpPublikVerify registration OTP and issue JWT
Body (wajib)
Respons
/auth/loginPublikLogin with email and password
Body (wajib)
Respons
/auth/refreshPublikRefresh JWT access token
Body (wajib)
Respons
/auth/logoutBearerAuthRevoke current session JWT token
Respons
/auth/meBearerAuthInspect user and merchant profile
Respons
/auth/api-key/rotateBearerAuthRotate tenant API Key (Owner only)
Respons
Lakukan panggilan POST untuk mendaftarkan data awal merchant:
curl -X POST "https://dagangbot.web.id/api/v1/auth/register" \
-H "Content-Type: application/json" \
-d '{
"merchant_name": "Toko Sejahtera",
"phone": "6281234567890",
"name": "Budi Santoso",
"email": "[email protected]",
"password": "PasswordKuat123!",
"accept_tos": true,
"accept_privacy": true
}'Sistem akan mengembalikan referensi user_id dan memicu pengiriman pesan WhatsApp berisi kode OTP 6 digit.
Langkah 2: Konfirmasi OTP untuk Penerbitan Token
/auth/registerPublikRegister merchant and trigger OTP
Body (wajib)
Respons
/auth/verify-otpPublikVerify registration OTP and issue JWT
Body (wajib)
Respons
/auth/loginPublikLogin with email and password
Body (wajib)
Respons
/auth/refreshPublikRefresh JWT access token
Body (wajib)
Respons
/auth/logoutBearerAuthRevoke current session JWT token
Respons
/auth/meBearerAuthInspect user and merchant profile
Respons
/auth/api-key/rotateBearerAuthRotate tenant API Key (Owner only)
Respons
Setelah pengguna menerima OTP dari WhatsApp DagangBot, kirimkan kembali kode tersebut ke server:
curl -X POST "https://dagangbot.web.id/api/v1/auth/verify-otp" \
-H "Content-Type: application/json" \
-d '{
"phone": "6281234567890",
"otp_code": "481923"
}'Respons sukses akan mengandung pasangan kredensial JWT sesi yang terdiri dari access_token dan refresh_token. Mulai dari titik ini, akun sudah aktif sepenuhnya.
Langkah 3: Pembuatan All-in-One API Key
Kunci API khusus integrasi mesin tidak diterbitkan otomatis. Administrator merchant harus menginisiasinya melalui dashboard.
- Arahkan kursor ke menu Pengaturan dan pilih Integrasi Pengembang.
- Pada tab All-in-One API Key, pilih Buat Kunci Baru.
- Di dalam modal Scope Picker, centang modul yang diizinkan (misalnya, hanya
orders:readdanproducts:read). - Klik konfirmasi. Sistem akan menampilkan kunci
dgb_all_...secara utuh. - Salin kunci tersebut ke Secret Manager atau variabel lingkungan (Environment Variable) aplikasi Anda. Sistem akan menutup modal dan kunci tidak akan pernah dapat diakses secara plaintext lagi.
Langkah 4: Melakukan Permintaan dengan API Key
Kunci API ini dikirimkan melalui header X-API-Key pada setiap HTTP Request yang menuju rute /api/v1/all-in-one/*.
Berikut contoh implementasi dalam beberapa bahasa pemrograman untuk membaca daftar pelanggan:
curl -X GET "https://dagangbot.web.id/api/v1/all-in-one/customers" \
-H "X-API-Key: dgb_all_XyZ123AbC456DeF789"Jangan pernah menaruh hardcode kunci API langsung di dalam source code repositori GitHub atau Gitlab Anda. Gunakan file .env untuk menyimpan rahasia secara aman.
Langkah 5: Rotasi Kunci (Key Rotation)
Praktik keamanan yang baik mengharuskan Anda memutar (merotasi) kunci API secara berkala atau seketika saat mencurigai adanya kebocoran data.
- Buka kembali panel Integrasi Pengembang.
- Klik tombol Rotasi Kunci.
- Sistem akan mencabut kunci lama (invalidasi instan ke cache Redis) dan menerbitkan kunci baru.
- Anda harus segera memperbarui konfigurasi server integrasi eksternal Anda dengan kunci yang baru untuk menghindari downtime.
4. Parameter & Spesifikasi Teknis
Mekanisme otorisasi dalam ekosistem DagangBot didesain untuk keandalan tinggi dan mitigasi kebocoran kredensial proaktif. Berbeda dengan platform monolitik yang mencampuradukkan kredensial administrator dan kunci mesin, sistem ini menerapkan pemisahan tugas (separation of duties) yang absolut di level jaringan.
Anatomi JSON Web Token (JWT) Sesi Manusia
Ketika pengguna memvalidasi OTP atau melakukan login dengan kata sandi yang valid, server merespons dengan struktur token JWT. Format string JWT ini terdiri dari tiga bagian yang dipisahkan oleh tanda titik (.): Header.Payload.Signature. Setiap bagian dikodekan dalam format Base64Url tanpa enkripsi (hanya penandatanganan).
- Header: Mendeklarasikan tipe token (
JWT) dan algoritma penandatanganan kriptografis yang digunakan. Untuk efisiensi tinggi dan keamanan terhadap serangan kuantum tingkat lanjut, DagangBot menggunakan algoritma kurva eliptik EdDSA (dengan kurva Ed25519) pada lingkungan produksi, meskipun lingkungan pengujian lokal mungkin fallback ke algoritma HMAC simetris HS256. - Payload (Klaim): Bagian ini memuat pernyataan entitas (pengguna/tenant) dan properti siklus hidup. Klaim yang selalu ada meliputi:
sub(Subject): Berisiuser_idunik berbentuk UUID v4.merchant_id: Identifier untuk sistem Row Level Security (RLS) PostgreSQL. Sangat krusial; apabila klaim ini hilang, koneksi akan ditolak seketika oleh middleware.role: Menentukan hierarki Role-Based Access Control (RBAC). Nilainya dapat berupaowner(kontrol penuh),manager, ataustaff(terbatas).iat(Issued At): Stempel waktu UNIX ketika token pertama kali dibuat oleh server otentikasi.exp(Expiration Time): Stempel waktu batas akhir masa berlaku token. Sesi interaktif biasanya memiliki durasiexpsangat pendek, berkisar antara 15 hingga maksimal 60 menit demi mencegah replikasi sesi oleh pihak jahat yang mencuri kuki browser.
- Signature: Tanda tangan digital ini memastikan integritas. Jika seorang penyerang memodifikasi klaim
roledaristaffmenjadiownerdan mengenkode ulang Base64-nya, kecocokan verifikasi signature pada server akan gagal secara matematis, mengembalikan galat401 Invalid Signature.
Struktur All-in-One API Key (dgb_all_)
Berbeda dengan JWT yang stateless dan membawa klaim di dalamnya, All-in-One API Key bersifat opaque (buram). Kunci ini berawalan konstan dgb_all_ diikuti oleh 32 hingga 64 karakter alfanumerik acak berentropi tinggi.
- Awalan
dgb_all_memungkinkan sistem pemindaian repositori otomatis (seperti GitHub Secret Scanning) untuk secara cepat mendeteksi jika kunci Anda tidak sengaja terekspos di repositori publik. - Kunci ini sepenuhnya stateful, artinya klaim akses (seperti scopes apa saja yang diizinkan) tidak melekat pada teks kuncinya, melainkan disimpan dengan aman di klaster memori Redis dan pangkalan data PostgreSQL milik DagangBot. Saat kunci dikirim, server melakukan pencarian
O(1)ke Redis untuk mengekstrak profil izinnya.
Kebijakan Pembatasan Kecepatan Lanjutan (Advanced Rate Limiting)
Sistem Pembatasan Scope Kustom (Custom Scopes)
Pada saat pembuatan All-in-One API Key, administrator dapat menerapkan pembatasan hak akses spesifik berdasarkan modul. Pendekatan ini mematuhi prinsip hak istimewa terendah (Principle of Least Privilege). Kunci hanya akan diizinkan mengeksekusi operasi yang dicentang saat inisialisasi. Berikut adalah matriks spesifikasi scope utama yang berlaku dalam sistem otorisasi:
Bila sebuah permintaan dari mesin perantara berusaha mengakses jalur yang tidak terdapat pada profil scope kunci, sistem router di lapisan jaringan seketika memantulkannya dengan status 403 Forbidden bersama laporan INSUFFICIENT_SCOPE. Keamanan ini dirancang selevel dengan otorisasi korporasi di perbankan, di mana kunci token untuk pembacaan saldo tidak bisa dipakai untuk pemindahan dana.
Mekanisme otorisasi DagangBot beroperasi pada level middleware yang mendecode header sebelum permintaan diserahkan ke handler layanan. Terdapat dua jenis header yang dievaluasi bergantung pada rute yang dipanggil:
Skema Transportasi Kredensial
Anatomi JSON Web Token (JWT)
Token access_token DagangBot ditandatangani menggunakan algoritma asimetris EdDSA (Ed25519) atau HS256 bergantung pada lingkungan penerapan. Payload klaim standar di dalamnya mencakup:
sub: ID Unik Pengguna (User ID).merchant_id: ID unik dari tenant atau bisnis (dasar dari Row Level Security).role: Peran RBAC pengguna (misalnya:owner,manager,staff).exp: Unix timestamp waktu kedaluwarsa token (biasanya 15 hingga 60 menit).iat: Unix timestamp saat token diterbitkan.
Proteksi Kecepatan Kueri (Rate Limiting)
Setiap kredensial tidak bebas melalukan spam permintaan tanpa batas. Infrastruktur DagangBot mengkategorikan rate limit menjadi beberapa profil Bucket:
- AuthLimit: Ketat berbasis alamat IP. Diterapkan pada rute pendaftaran dan pengiriman OTP (
/auth/*) untuk mencegah eksploitasi biaya dan Brute Force. - SensitiveLimit: Pembatasan moderat (contoh: 10 request per menit) pada titik akhir yang berbiaya langsung, seperti mengirimkan notifikasi WhatsApp atau pengisian saldo.
- GeneralLimit: Pembatasan standar (contoh: 100 request per menit) untuk pembacaan data katalog produk atau pelanggan.
Setiap respon penolakan batas akan mengembalikan status 429 Too Many Requests disertai header Retry-After.
Praktik Terbaik Penyimpanan Rahasia (Secret Management)
Pengembang sering kali tergelincir dalam mengelola API Key. Kami menyarankan penerapan manajemen siklus hidup kunci sebagai berikut:
- Di Lingkungan Lokal: Gunakan berkas
.env.localdan pastikan ekstensi.env*terdaftar di dalam.gitignore. Jangan pernah menginisialisasi variabel kunci langsung di fail kode sumber. - Di Lingkungan CI/CD (GitHub Actions/GitLab CI): Manfaatkan antarmuka Settings > Secrets and variables untuk mendeklarasikan nilai
DAGANGBOT_ALL_IN_ONE_KEY. Jangan cetak nilainya pada tahapan build atau echo. - Di Produksi Modern (Vercel/AWS/GCP): Simpan kunci menggunakan layanan pengelolaan khusus seperti AWS Secrets Manager, Google Cloud Secret Manager, atau HashiCorp Vault. Layanan ini memberikan audit jejak siapa saja yang pernah membaca kunci tersebut.
5. Relasi & Integrasi
Subsistem autentikasi bertindak sebagai penjaga gerbang sentral (Central Gateway Guard) bagi seluruh arsitektur backend di dalam kerangka kerja DagangBot. Keterikatan komponen autentikasi dengan lapisan teknis lain sangat erat:
Konektivitas dengan Cache Redis Berperforma Tinggi
Untuk memastikan latensi kueri yang rendah pada sistem dengan throughput jutaan request, pembacaan token sesi maupun API Key tidak divalidasi langsung ke pangkalan data PostgreSQL setiap saat. Sebaliknya:
- Setelah sukses login atau pertama kali API Key di-load, profil autentikasi akan di- cache dalam memori klaster Redis.
- Kunci Redis memiliki pola spesifik:
apikey:{hash}atausession:{user_id}. - Operasi modifikasi (logout atau pencabutan kunci) bersifat atomik: menghapus row di Postgres dan mendelete kunci di Redis dalam satu siklus. Hasilnya, invalidasi sesi bersifat absolut dan instan (di bawah 5 milidetik).
Pengamanan Database lewat Row Level Security (RLS)
Integrasi utama JWT dan API key adalah pemompaan variabel sesi (Session Context) ke tingkat koneksi basis data. Segera setelah permintaan berhasil menembus lapisan middleware autentikasi, server aplikasi (Chi Router dalam Golang) akan mengambil klaim merchant_id. ID ini kemudian disuntikkan ke kueri eksekusi:
SET LOCAL app.current_tenant_id = '12345-abcde';Kebijakan Row Level Security di PostgreSQL akan secara otomatis menambahkan kondisi filtrasinya. Sebagai contoh, saat integrasi Anda menjalankan GET produk, di tingkat database kueri yang dijalankan adalah SELECT * FROM products WHERE merchant_id = current_tenant_id. Ini adalah mitigasi absolut terhadap risiko BOLA (Broken Object Level Authorization).
Pagar Pembatas IP (IP Allowlist Gate)
Sebagai lapisan defense in depth ganda, portal keamanan menyediakan IP Allowlist. Ketika diaktifkan oleh admin:
- Setiap permintaan menggunakan API Key akan dievaluasi alamat IP klien asalnya.
- IP klien akan dicocokkan terhadap pendaftaran notasi Classless Inter-Domain Routing (CIDR).
- Apabila alamat IP publik aplikasi integrator tidak terdaftar di daftar aman, gateway memblokir transaksi meskipun token API Key valid 100%.
Ini sangat berguna apabila kunci API Anda diretas secara eksternal. Penyerang tetap tidak bisa menggunakannya karena alamat IP mereka akan ditolak.
Mekanika Rotasi Kredensial Tanpa Downtime
Salah satu tantangan terbesar dalam memelihara aplikasi berkaliber Enterprise adalah bagaimana memutar kunci yang bocor tanpa mengganggu ratusan transaksi per detik yang sedang berjalan. Platform DagangBot mendesain sistem rotasinya secara asinkron. Anda dapat membuat kunci AIO kedua (sistem mendukung hingga 3 kunci simultan) sebelum mencabut kunci pertama. Ini memungkinkan deployment aplikasi integrator secara bertahap menggunakan kredensial baru, dan setelah traffic pada kredensial lama menjadi nol, Anda dapat dengan aman menghapus kredensial yang lama dari panel dasbor.
6. Pemecahan Masalah (Troubleshooting)
Permasalahan autentikasi bisa sangat memusingkan apabila pesan galat tidak diurai secara logis. Untuk memfasilitasi operasional tanpa henti (24/7), integrasi sistem Anda wajib memiliki penanganan mandiri (self-healing) terhadap beberapa kelas kesalahan yang lazim.
Mendiagnosis Clock Skew pada JWT
Masalah terselubung yang sering membuat peladen integrasi Anda tiba-tiba menerima 401 Unauthorized secara fluktuatif adalah inkonsistensi waktu jam server (Clock Skew).
Ketika Anda memanggil titik akhir /auth/login, server menerbitkan token dengan batas expired (exp). Jika jam server klien Anda berjalan lebih cepat dari jam atom standar global (NTP), klien Anda mungkin secara keliru menganggap token sudah mati meskipun masih valid, atau sebaliknya, mencoba menggunakan token yang ternyata baru saja berakhir menurut jam server DagangBot. Solusi pamungkasnya adalah mengatur cron daemon pembaruan Network Time Protocol (NTP) agar menyinkronkan jam OS secara kontinu.
Melakukan Eksponensial Backoff untuk HTTP 429
Ketika API Anda merespons dengan galat Rate Limit Exceeded, memaksa pengulangan kueri secara agresif justru akan membuat IP Anda di-blacklist sementara oleh firewall L7 (Layer 7). Skrip worker Anda harus diprogram dengan algoritma Exponential Backoff yang membaca header Retry-After.
Contoh logika mitigasinya adalah sebagai berikut:
- Eksekusi panggilan HTTP.
- Jika menerima
429, periksa headerRetry-After(biasanya dalam hitungan detik). - Lakukan
sleepsinkronus atau jedasetTimeoutsesuai jumlah detik tersebut. - Apabila tidak ada header, gunakan jeda eksponensial standar (awal 1 detik, lalu 2 detik, 4 detik, dan seterusnya hingga maksimal 32 detik percobaan).
- Lakukan retri kembali. Jika sukses, riset konter eksponensial.
Integrasi dan otentikasi seringkali memberikan pesan galat ketika format tidak sempurna. Tabel berikut memuat matrik diagnostik cepat:
7. Kode Error & Penanganan
Daftar spesifikasi kode status respons HTTP spesifik dari lapisan otorisasi yang wajib ditangani (caught) pada skrip layanan eksternal Anda:
8. Referensi Terkait
Pemahaman mengenai fondasi ini hanyalah awal. Untuk melanjutkan perjalanan teknis di dalam platform, silakan telusuri referensi implementasi langsung berikut:
Konsep Inti Platform
Pelajari lebih dalam metodologi Row Level Security (RLS) dan isolasi data per merchant DagangBot.
Katalog Endpoint All-in-One API
Jelajahi matriks 46 endpoint yang siap diakses dengan API Key Anda untuk integrasi penuh.
Referensi REST API Dasar
Tinjau daftar komprehensif endpoint dashboard dan referensi kode kesalahan secara umum.
Konfigurasi Webhook Outbound
Panduan menerima event asinkron real-time, dibekali validasi tanda tangan keamanan SHA256.
