Bab 13 · Developer API
Autentikasi & Batas Pemakaian
Cara membuat dan memakai API key (Bearer lsk_live_...), arti setiap error 401, batas 60 request/menit per key, dan praktik keamanan.
Membuat API key
API key dibuat sendiri dari dalam aplikasi, di menu Pengaturan → API Key (butuh izin setting:api-key).
- Klik Buat API Key.
- Isi Nama — deskripsi integrasinya, misalnya
Integrasi Google SheetsatauDashboard Keuangan Internal. - Isi masa kedaluwarsa dalam hari, atau kosongkan kalau key berlaku selamanya.
- Key ditampilkan sekali saja setelah dibuat. Salin dan simpan segera.
Daftar key menampilkan kolom Nama, Dibuat Oleh, Dibuat, Terakhir Dipakai, Kedaluwarsa, dan Status — berguna untuk mengecek apakah sebuah integrasi masih hidup. Kolom Terakhir Dipakai diperbarui paling cepat sekali per menit, jadi wajar kalau tidak berubah di setiap request.
Lensiro tidak menyimpan key dalam bentuk aslinya — hanya hash SHA-256 dan 4 karakter terakhir untuk ditampilkan. Artinya tim Lensiro pun tidak bisa memberitahu key lama Anda. Kalau hilang: cabut, lalu buat baru.
Format dan cara pakai
Key berbentuk lsk_live_ diikuti 43 karakter acak:
lsk_live_7Kq2mZx9Rb4TnV1cWp8yLd6EhG3sJuA5oF0iQrXtN2M
Kirim di setiap request lewat header Authorization:
curl -H "Authorization: Bearer lsk_live_xxxxxxxx" \
"https://app-anda.lensiro.com/api/v1/sales"
Tidak ada cara lain — key tidak bisa dikirim lewat query string atau cookie.
Apa yang bisa diakses sebuah key
- Semua data yang diekspos API ini, di semua cabang. Belum ada scope maupun pembatasan per cabang di v1.
- Hanya baca. Key tidak bisa mengubah apa pun.
Karena satu key berarti akses baca penuh, perlakukan key seperti password admin. Kalau Anda perlu memberi akses ke pihak ketiga yang hanya boleh melihat sebagian data, tunggu dukungan scoped key (lihat Batasan, Versi & Rencana) — jangan berikan key penuh.
Error autentikasi
| HTTP | error.code | Arti | Yang harus dilakukan |
|---|---|---|---|
| 401 | missing_api_key | Header Authorization: Bearer ... tidak ada atau salah bentuk | Periksa penulisan header, termasuk spasi setelah Bearer |
| 401 | invalid_api_key | Key tidak dikenal, atau tidak diawali lsk_ | Pastikan key tersalin utuh, tanpa spasi atau baris baru |
| 401 | revoked_api_key | Key sudah dicabut lewat menu API Key | Buat key baru |
| 401 | expired_api_key | Key sudah melewati tanggal kedaluwarsa | Buat key baru |
Bentuk body error selalu sama:
{ "error": { "code": "invalid_api_key", "message": "The API key is not valid." } }
Batas pemakaian (rate limit)
Ada dua lapis batas, keduanya memakai jendela geser 60 detik:
| Batas | Nilai | Dihitung per |
|---|---|---|
| Per API key | 60 request / menit | key |
| Per alamat IP | 120 request / menit | IP pemanggil |
Batas per IP diperiksa sebelum key divalidasi, jadi request dengan key salah pun ikut terhitung.
Saat terlampaui, API membalas:
HTTP/1.1 429 Too Many Requests
Retry-After: 37
{ "error": { "code": "rate_limited", "message": "Rate limit exceeded (60 requests/minute)." } }
Cara menanganinya: tunggu sebanyak detik yang tertulis di Retry-After, lalu ulangi request yang sama. Jangan mencoba ulang dalam loop ketat.
Sebagai gambaran, menarik data tiap jam dari empat endpoint hanya memakai beberapa request per jam. Batas ini baru terasa saat backfill besar — di kasus itu, beri jeda sekitar satu detik antar halaman.
Praktik keamanan
- Jangan pernah menaruh key di frontend, aplikasi mobile, repositori publik, atau spreadsheet yang dibagikan. Semua yang berjalan di browser bisa dibaca pengguna.
- Simpan key sebagai environment variable atau di secret manager. Di Google Apps Script, pakai Script Properties, bukan konstanta di dalam kode.
- Satu integrasi, satu key. Kalau nanti perlu dicabut, integrasi lain tidak ikut mati.
- Cabut key yang sudah tidak dipakai. Kolom Terakhir Dipakai membantu menemukannya.
- Rotasi berkala: buat key baru → pindahkan integrasi → pastikan berjalan → cabut key lama. Karena kedua key valid bersamaan, tidak ada waktu mati.
- Kalau key diduga bocor, cabut sekarang lalu buat baru. Pencabutan langsung berlaku.
