Autentikasi dan kunci API

Setiap permintaan ke Developer API memakai kunci API di header Authorization. Kunci dibuat di menu Developer OngkirHub App dan menentukan tiga hal: workspace yang diakses, mode test atau live, dan endpoint yang boleh dipanggil.

curl https://api.ongkirhub.com/v1/couriers \
  -H "Authorization: Bearer ohk_test_xxx"

Bentuk kunci

Kunci terdiri dari awalan mode dan 32 karakter heksadesimal.

Awalan	Mode	Yang terjadi
ohk_test_	Test	Simulasi: tarif, resi, dan pelacakan dibuat simulator OngkirHub. Tidak ada kurir yang datang dan saldo sungguhan tidak tersentuh.
ohk_live_	Live	Pesanan sungguhan ke kurir dan memotong saldo OngkirHub.

Data kedua mode terpisah sepenuhnya. Penjelasan lengkapnya ada di Mode test.

Membuat kunci

Hanya pemilik dan admin workspace yang bisa membuka menu Developer.

1. Masuk ke OngkirHub App, lalu buka menu Developer, tab Kunci API.
2. Tekan Buat kunci.
3. Isi Nama kunci, misalnya “Server toko” atau “Staging”, supaya mudah dikenali di Log API.
4. Pilih Mode: Test atau Live.
5. Pilih Akses yang dibutuhkan integrasimu. Semua akses dicentang secara bawaan.
6. Tekan Buat kunci, salin kunci yang tampil, lalu tekan Sudah saya simpan.

Kunci lengkap hanya ditampilkan sekali. Setelah dialog ditutup, daftar kunci hanya menampilkan awalannya. Satu workspace bisa punya sampai 20 kunci aktif.

Akses (scope)

Setiap kunci punya satu atau beberapa akses. Endpoint menolak kunci tanpa akses yang dibutuhkan dengan 403 forbidden, dan details.requiredScope menyebut akses yang kurang.

Akses	Label di menu Developer	Endpoint
locations:read	Cari lokasi	GET /v1/locations
couriers:read	Daftar kurir	GET /v1/couriers
rates:read	Cek ongkir	POST /v1/rates
shipments:read	Lihat pengiriman	GET /v1/shipments, GET /v1/shipments/{id}
shipments:write	Buat dan batalkan pengiriman	POST /v1/shipments, POST /v1/shipments/{id}/cancel
tracking:read	Lacak resi	GET /v1/tracking/{awb}
wallet:read	Lihat saldo dan mutasi	GET /v1/wallet, GET /v1/wallet/transactions

Beri setiap kunci akses seminimal mungkin. Contohnya, kunci untuk halaman checkout yang hanya menampilkan ongkir cukup memakai locations:read dan rates:read.

GET /v1/openapi.json bisa diambil tanpa kunci.

Menyimpan kunci dengan aman

• Simpan kunci di server, misalnya di variabel lingkungan, bukan di kode sumber atau repositori.
• Jangan taruh kunci di aplikasi browser atau aplikasi mobile. API ini tidak mengirim header CORS, jadi panggil dari backend kamu.
• Pakai kunci terpisah untuk setiap sistem atau lingkungan, misalnya satu untuk server produksi dan satu untuk staging. Dengan begitu, satu kunci bisa dicabut tanpa mengganggu sistem lain.
• Pantau pemakaian di tab Log API. Log ini mencatat paling banyak 60 permintaan per kunci per menit, jadi simpan juga header X-Request-Id di log servermu. Kolom Terakhir dipakai di daftar kunci membantu menemukan kunci yang tidak dipakai lagi.

Mencabut kunci

Di tab Kunci API, tekan Cabut di baris kunci, lalu konfirmasi dengan Cabut kunci. Permintaan dengan kunci itu langsung ditolak dengan 401 unauthenticated. Pencabutan tidak bisa dibatalkan.

Mengganti kunci (rotasi)

Kunci tidak bisa diperbarui di tempat. Untuk mengganti kunci, misalnya karena kunci lama mungkin bocor atau ada anggota tim yang keluar, buat kunci baru lalu cabut yang lama:

1. Buat kunci baru dengan mode dan akses yang sama.
2. Pasang kunci baru di server kamu dan deploy.
3. Pastikan permintaan dengan kunci baru muncul di Log API dan kolom Terakhir dipakai kunci lama berhenti bertambah.
4. Cabut kunci lama.

Kalau kunci lama bocor, cabut segera tanpa menunggu langkah 3, lalu periksa Log API untuk permintaan yang tidak kamu kenali.

Error autentikasi

Status	code	Penyebab
401	unauthenticated	Header Authorization tidak dikirim, formatnya bukan Bearer <kunci>, kunci salah, atau kunci sudah dicabut.
403	forbidden	Kunci valid tetapi tidak punya akses untuk endpoint ini. Lihat details.requiredScope.
429	rate_limited	Terlalu banyak percobaan dengan kunci yang tidak valid dari alamat IP yang sama. Tunggu sesuai header Retry-After.

Daftar lengkap kode error ada di Error.