Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

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.

Stable

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.
Isolasi Dua Arah (Two-Way Guard)

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:

Kartu API Key All-in-One live di dasbor integrasi DagangBot
Panel API Key All-in-One terpadu dengan indikator status aktif, tombol rotasi kunci, dan contoh cURL otentikasi.
Dasbor manajemen integrasi pengembang dengan IP whitelist resmi dan allowlist klien
Dasbor pengelolaan integrasi pengembang dengan banner IP resmi server, manajemen IP allowlist klien, dan monitoring kuota token.

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.

POST/auth/registerPublik

Register merchant and trigger OTP

Body (wajib)

FieldWajibTipeDeskripsi
merchant_nameYastring-
phoneYastring-
nameYastring-
emailYastring-
passwordYastring-
accept_tosYaboolean-
accept_privacyYaboolean-
contoh-body.json
{
  "merchant_name": "Toko Saya",
  "phone": "6281234567890",
  "name": "Contoh Nama",
  "email": "[email protected]",
  "password": "KataSandi123",
  "accept_tos": true,
  "accept_privacy": true
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{ "merchant_name": "Toko Saya", "phone": "6281234567890", "name": "Contoh Nama", "email": "[email protected]", "password": "KataSandi123", "accept_tos": true, "accept_privacy": true }'

Respons

StatusDeskripsi
201Registration initiated, OTP sent
POST/auth/verify-otpPublik

Verify registration OTP and issue JWT

Body (wajib)

FieldWajibTipeDeskripsi
phoneYastring-
otp_codeYastring-
contoh-body.json
{
  "phone": "6281234567890",
  "otp_code": "123456"
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "6281234567890", "otp_code": "123456" }'

Respons

StatusDeskripsi
200Tokens issued
POST/auth/loginPublik

Login with email and password

Body (wajib)

FieldWajibTipeDeskripsi
emailYastring-
passwordYastring-
contoh-body.json
{
  "email": "[email protected]",
  "password": "KataSandi123"
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "KataSandi123" }'

Respons

StatusDeskripsi
200Login successful
429Brute force lockout triggered
POST/auth/refreshPublik

Refresh JWT access token

Body (wajib)

FieldWajibTipeDeskripsi
refresh_tokenYastring-
contoh-body.json
{
  "refresh_token": "<token>"
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "<token>" }'

Respons

StatusDeskripsi
200New token pair issued
POST/auth/logoutBearerAuth

Revoke current session JWT token

curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/logout" \
  -H "Authorization: Bearer $DAGANGBOT_TOKEN"

Respons

StatusDeskripsi
200Token revoked and added to blacklist
GET/auth/meBearerAuth

Inspect user and merchant profile

curl
curl -X GET "https://dagangbot.co.id/api/v1/auth/me" \
  -H "Authorization: Bearer $DAGANGBOT_TOKEN"

Respons

StatusDeskripsi
200Profile retrieved
POST/auth/api-key/rotateBearerAuth

Rotate tenant API Key (Owner only)

curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/api-key/rotate" \
  -H "Authorization: Bearer $DAGANGBOT_TOKEN"

Respons

StatusDeskripsi
200New API Key generated

Lakukan panggilan POST untuk mendaftarkan data awal merchant:

bash
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

POST/auth/registerPublik

Register merchant and trigger OTP

Body (wajib)

FieldWajibTipeDeskripsi
merchant_nameYastring-
phoneYastring-
nameYastring-
emailYastring-
passwordYastring-
accept_tosYaboolean-
accept_privacyYaboolean-
contoh-body.json
{
  "merchant_name": "Toko Saya",
  "phone": "6281234567890",
  "name": "Contoh Nama",
  "email": "[email protected]",
  "password": "KataSandi123",
  "accept_tos": true,
  "accept_privacy": true
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{ "merchant_name": "Toko Saya", "phone": "6281234567890", "name": "Contoh Nama", "email": "[email protected]", "password": "KataSandi123", "accept_tos": true, "accept_privacy": true }'

Respons

StatusDeskripsi
201Registration initiated, OTP sent
POST/auth/verify-otpPublik

Verify registration OTP and issue JWT

Body (wajib)

FieldWajibTipeDeskripsi
phoneYastring-
otp_codeYastring-
contoh-body.json
{
  "phone": "6281234567890",
  "otp_code": "123456"
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "6281234567890", "otp_code": "123456" }'

Respons

StatusDeskripsi
200Tokens issued
POST/auth/loginPublik

Login with email and password

Body (wajib)

FieldWajibTipeDeskripsi
emailYastring-
passwordYastring-
contoh-body.json
{
  "email": "[email protected]",
  "password": "KataSandi123"
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "KataSandi123" }'

Respons

StatusDeskripsi
200Login successful
429Brute force lockout triggered
POST/auth/refreshPublik

Refresh JWT access token

Body (wajib)

FieldWajibTipeDeskripsi
refresh_tokenYastring-
contoh-body.json
{
  "refresh_token": "<token>"
}
curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "<token>" }'

Respons

StatusDeskripsi
200New token pair issued
POST/auth/logoutBearerAuth

Revoke current session JWT token

curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/logout" \
  -H "Authorization: Bearer $DAGANGBOT_TOKEN"

Respons

StatusDeskripsi
200Token revoked and added to blacklist
GET/auth/meBearerAuth

Inspect user and merchant profile

curl
curl -X GET "https://dagangbot.co.id/api/v1/auth/me" \
  -H "Authorization: Bearer $DAGANGBOT_TOKEN"

Respons

StatusDeskripsi
200Profile retrieved
POST/auth/api-key/rotateBearerAuth

Rotate tenant API Key (Owner only)

curl
curl -X POST "https://dagangbot.co.id/api/v1/auth/api-key/rotate" \
  -H "Authorization: Bearer $DAGANGBOT_TOKEN"

Respons

StatusDeskripsi
200New API Key generated

Setelah pengguna menerima OTP dari WhatsApp DagangBot, kirimkan kembali kode tersebut ke server:

bash
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.

  1. Arahkan kursor ke menu Pengaturan dan pilih Integrasi Pengembang.
  2. Pada tab All-in-One API Key, pilih Buat Kunci Baru.
  3. Di dalam modal Scope Picker, centang modul yang diizinkan (misalnya, hanya orders:read dan products:read).
  4. Klik konfirmasi. Sistem akan menampilkan kunci dgb_all_... secara utuh.
  5. 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:

bash
curl -X GET "https://dagangbot.web.id/api/v1/all-in-one/customers" \
  -H "X-API-Key: dgb_all_XyZ123AbC456DeF789"
Perlindungan Kode

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.

  1. Buka kembali panel Integrasi Pengembang.
  2. Klik tombol Rotasi Kunci.
  3. Sistem akan mencabut kunci lama (invalidasi instan ke cache Redis) dan menerbitkan kunci baru.
  4. 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).

  1. 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.
  2. Payload (Klaim): Bagian ini memuat pernyataan entitas (pengguna/tenant) dan properti siklus hidup. Klaim yang selalu ada meliputi:
    • sub (Subject): Berisi user_id unik 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 berupa owner (kontrol penuh), manager, atau staff (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 durasi exp sangat pendek, berkisar antara 15 hingga maksimal 60 menit demi mencegah replikasi sesi oleh pihak jahat yang mencuri kuki browser.
  3. Signature: Tanda tangan digital ini memastikan integritas. Jika seorang penyerang memodifikasi klaim role dari staff menjadi owner dan mengenkode ulang Base64-nya, kecocokan verifikasi signature pada server akan gagal secara matematis, mengembalikan galat 401 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:

Nama Scope Akses Fungsionalitas Modul Tingkat Risiko Dampak Pembatasan
wa:manage Mengelola sesi dan mendaftarkan instans WhatsApp baru. Tinggi Pemegang kunci dapat memanipulasi jembatan komunikasi ke server WhatsApp Cloud.
orders:create Menulis dan mengubah entitas transaksi pemesanan konsumen. Sangat Tinggi Akses penuh atas pencatatan arus kas dan status pengiriman barang fisik.
products:read Menarik katalog produk secara berkelompok tanpa mengubahnya. Rendah Aman untuk diberikan kepada aplikasi agregator inventaris publik karena bersifat hanya baca.
billing:topup Menambahkan saldo sistem menggunakan kuota otomatis. Kritis Rute ini dijaga ketat oleh pembatas kecepatan dan wajib disertai kunci idempotensi untuk menghindari kerugian uang akibat transaksi ganda.
customers:read Membaca daftar identitas dan riwayat belanja konsumen. Sedang Harus dibatasi dari pihak ketiga karena potensi pencurian data privasi pelanggan (PII).

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

Metode Otorisasi Header HTTP Target Format Nilai Target Ekosistem
Sesi JWT Manusia Authorization Bearer eyJhb... /api/v1/* (Non AIO)
Integrasi Eksternal X-API-Key dgb_all_[A-Za-z0-9]{32} /api/v1/all-in-one/*

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:

  1. AuthLimit: Ketat berbasis alamat IP. Diterapkan pada rute pendaftaran dan pengiriman OTP (/auth/*) untuk mencegah eksploitasi biaya dan Brute Force.
  2. SensitiveLimit: Pembatasan moderat (contoh: 10 request per menit) pada titik akhir yang berbiaya langsung, seperti mengirimkan notifikasi WhatsApp atau pengisian saldo.
  3. 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.local dan 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} atau session:{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:

sql
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:

  1. Setiap permintaan menggunakan API Key akan dievaluasi alamat IP klien asalnya.
  2. IP klien akan dicocokkan terhadap pendaftaran notasi Classless Inter-Domain Routing (CIDR).
  3. 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:

  1. Eksekusi panggilan HTTP.
  2. Jika menerima 429, periksa header Retry-After (biasanya dalam hitungan detik).
  3. Lakukan sleep sinkronus atau jeda setTimeout sesuai jumlah detik tersebut.
  4. Apabila tidak ada header, gunakan jeda eksponensial standar (awal 1 detik, lalu 2 detik, 4 detik, dan seterusnya hingga maksimal 32 detik percobaan).
  5. 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:

Gejala Teramati Penyebab Paling Mungkin Rekomendasi Solusi & Perbaikan
Mendapat HTTP 401 Unauthorized saat menggunakan kunci AIO Format kunci di header salah atau menggunakan tipe Bearer alih-alih X-API-Key Pastikan mengirim X-API-Key: dgb_all_... persis tanpa tanda kutip. Pastikan kunci belum dirotasi.
Menerima balasan 403 Forbidden meskipun kunci sudah benar 1. Isu Two-Way Guard: menembak endpoint dashboard dengan AIO Key.2. Scope kurang. Arahkan URL Anda spesifik pada ekosistem /api/v1/all-in-one/*. Pastikan scope yang relevan tercentang di dasbor.
Aplikasi Frontend mendapatkan galat CORS Blocked Rute All-in-One API Key secara ketat menolak permintaan dari browser (tanpa Preflight aman). Integrasi mesin ditujukan untuk Komunikasi Backend-ke-Backend. Sembunyikan panggilan API dari sisi klien.
Kueri terhenti pada galat HTTP 429 Rate Limited Volume permintaan melebihi kuota profil bucket limit yang berlaku. Terapkan pola algoritma retri terprogram (Exponential Backoff) pada klien integrasi Anda.

7. Kode Error & Penanganan

Daftar spesifikasi kode status respons HTTP spesifik dari lapisan otorisasi yang wajib ditangani (caught) pada skrip layanan eksternal Anda:

Kode HTTP Penanda Kesalahan (Error Code) Deskripsi Teknis
401 AUTH_TOKEN_MISSING Header otorisasi absen secara keseluruhan.
401 AUTH_TOKEN_EXPIRED Waktu berlaku Access Token (JWT) kedaluwarsa.
401 API_KEY_REVOKED API Key telah diinvalidasi melalui rotasi Dasbor.
403 INSUFFICIENT_SCOPE Payload atau kunci kekurangan hak istimewa operasional.
403 IP_ADDRESS_DENIED Alamat IP pemanggil ditolak oleh blokade Allowlist.
422 VALIDATION_ERROR Payload tidak memenuhi ekspektasi tipe atau skema mutlak.
422 INVALID_PHONE Format pendaftaran nomor telepon melanggar normalisasi.
429 RATE_LIMIT_EXCEEDED Serangan flood atau permintaan melebihi ambang kewajaran.

8. Referensi Terkait

Pemahaman mengenai fondasi ini hanyalah awal. Untuk melanjutkan perjalanan teknis di dalam platform, silakan telusuri referensi implementasi langsung berikut:

content/docs/integrations/authentication.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot