Autentikasi Dan Cakupan

Sistem Anda memanggil API AI Box dengan token sebuah akun API. Akun itu milik sistem Anda, memiliki namanya sendiri di log audit, dan hanya melihat lokasi serta data yang diberikan kepadanya.

Membuat Akun API

Admin membuat akun di dasbor, pada halaman Akun API:

1. Beri nama (3 sampai 64 karakter a-z, 0-9 dan . _ -, misalnya erp-sync). Log audit menampilkan panggilannya sebagai api:erp-sync.
2. Beri peran di satu lokasi atau lebih: Pemantau untuk membaca, Admin untuk juga mengubah pengaturan lokasi itu.
3. Pilih cakupannya (di bawah) dan tanggal berakhir, paling lama satu tahun ke depan.
4. Simpan, lalu salin tokennya. Token hanya ditampilkan kali ini.

Token berbentuk arsa_pat_ diikuti 43 karakter. Simpan sebagai rahasia di sistem Anda. Jika bocor, buat token baru di halaman yang sama (Buat token baru): token lama langsung berhenti berlaku. Cabut menghentikan akun untuk seterusnya; panggilannya tetap ada di log audit.

Pemilik perangkat mengelola setiap akun. Admin suatu lokasi mengelola akun yang semua lokasinya ia kelola.

Mengirim Token

Kirim token di header Authorization, setelah kata Bearer dan satu spasi:

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/v1/sites"

Token tidak memerlukan sesi maupun token CSRF. Cookie yang dikirim bersamanya diabaikan.

Sertifikat Perangkat

Dasbor melayani HTTPS dengan sertifikat milik perangkat. Berikan salinannya kepada klien Anda (box.pem di atas) agar sambungan terverifikasi.

Pada ARSA AI Video Analytics Software, sertifikatnya adalah sertifikat yang dilayani dasbor di server Anda; panel yang sama menampilkan dan mengunduhnya, dan nama yang dicakupnya adalah milik server Anda.

Sambungkan dengan nama host perangkat atau dengan alamat LAN-nya: sertifikat milik perangkat mencakup keduanya, juga <host>.local. Admin melihat nama dan alamat yang dicakupnya di samping tombol unduh (Berlaku untuk), dan getBoxCertificateInfo mencantumkannya sebagai names. Pakai salah satunya sebagai <BOX_HOST>, karena jika tidak, klien menolak sambungan.

• Dari Admin: Admin mengunduhnya di dasbor (Sistem, lalu Akun API, lalu Unduh sertifikat perangkat) dan memberikan berkas itu kepada Anda beserta sidik jari SHA-256 yang tampil di samping tombol.
• Dengan token Anda: akun dengan cakupan read dapat mengambilnya sendiri (getBoxCertificate). Klien Anda belum memercayai perangkat, jadi unduhan pertama ini melewati pemeriksaan (--insecure); pemeriksaan sidik jari di bawah menggantikannya.

curl --insecure \
  -H "Authorization: Bearer <API_KEY>" \
  -o box.pem \
  "https://<BOX_HOST>/api/v1/system/certificate"

Dengan cara mana pun, bandingkan sidik jari berkas dengan sidik jari yang dibaca Admin di dasbor sebelum Anda memakainya:

openssl x509 -noout -fingerprint -sha256 -in box.pem

Jika berbeda, jangan pakai berkas itu dan beri tahu Admin. Sertifikat baru di perangkat (misalnya sertifikat milik pelanggan) memiliki sidik jari baru: ambil berkasnya lagi dan bandingkan lagi.

Hal yang sama terjadi jika alamat perangkat berubah (sewa DHCP baru, jaringan lain): saat dinyalakan berikutnya, perangkat menerbitkan ulang sertifikatnya untuk alamat baru dengan kunci yang sama, dan sidik jarinya berubah. Unduh berkasnya lagi, periksa sidik jari baru dengan Admin, lalu ganti salinan lama di klien Anda.

Cakupan

Cakupan	Mengizinkan
read	Permintaan GET: data dan pengaturan
write	Perubahan: POST, PUT, PATCH, DELETE (pengaturan, menandai peringatan, entri daftar pantau)
export	Mengunduh file: ekspor log, laporan, rekaman dan klip
personal_data	Nama, nomor polisi, wajah, foto bukti, potongan gambar dan video

Setiap operasi di referensi mencantumkan cakupan dan peran lokasi yang diperlukannya. Panggilan tanpa cakupan yang diperlukan dijawab 403 dengan kode scope_required.

Hanya pemilik perangkat yang dapat memberi personal_data, dan dasbor meminta pemilik mengonfirmasi dengan kata sandi dan kode dua langkahnya.

Data Pribadi Dan Bentuk Anonim

Tanpa personal_data, sebagian operasi menjawab dengan bentuk anonim dan sebagian lainnya ditolak:

• Bentuk anonim: log deteksi Basic Safety Guard dan ekspornya (tanpa nama, tanpa bukti, named: false); log kendaraan Traffic Monitor, ekspornya dan insiden (tanpa nomor polisi, tanpa potongan gambar); peringatan (details tanpa nomor polisi, orang, nama, bukti atau media, dan tanpa rekaman).
• Ditolak: video langsung, rekaman dan klip, cuplikan kamera, kontak peringatan dan log pengirimannya, angka per pekerja dan gambar bukti Basic Safety Guard, daftar pantau Traffic Monitor, potongan gambar kendaraan dan pencarian log berdasarkan nomor polisi.

Smart Retail Counter dan DOOH Audience Meter menghitung orang secara anonim, sehingga API keduanya tidak memuat data pribadi.

Setiap panggilan akun yang memiliki personal_data, setiap ekspor dan setiap perubahan dicatat di log audit perangkat.

Yang Tidak Dapat Dilakukan Token

Sebagian tindakan memerlukan orang yang masuk ke dasbor. Tindakan itu dijawab 403 dengan kode api_account_refused untuk token apa pun: masuk dan kata sandi, pengguna dan akun API, lisensi, pembaruan, akses jarak jauh, pemeliharaan dan akses dukungan ARSA, pengaturan privasi, basis data wajah dan saluran notifikasi. Membuat kunci dan token umpan mesin juga ditolak; Admin lokasi membuatnya di dasbor.

Batas Laju

Setiap akun API boleh membuat 600 permintaan per menit secara bawaan (pemilik perangkat dapat mengubah batasnya). Di atas batas itu perangkat menjawab 429 dengan kode rate_limited dan header Retry-After dalam detik. Tunggu selama itu, lalu lanjutkan.

Galat

Galat berupa problem details RFC 9457 (application/problem+json) dengan code yang tetap, title singkat, status dan sering kali detail:

{
  "code": "scope_required",
  "title": "Forbidden",
  "status": 403,
  "detail": "This call needs the scope read."
}

Status	Kode	Arti
400	bad_request, malformed_json	Permintaan tidak berbentuk benar
401	token_invalid	Token tidak ada, salah, dicabut atau kedaluwarsa (dengan WWW-Authenticate: Bearer)
403	scope_required	Akun tidak memiliki cakupan yang diperlukan operasi
403	api_account_refused	Operasi hanya untuk orang di dasbor
404	misalnya site_not_found	Objek tidak ada, atau akun tidak memiliki peran di lokasinya
409	misalnya changed_meanwhile	Konflik, misalnya version yang sudah usang
412	version_mismatch	ETag yang dikirim di If-Match sudah usang
413	body_too_large	Isi permintaan terlalu besar
422	misalnya invalid_body	Sebagian kolom tidak valid; errors mencantumkan masing-masing dengan pointer dan detail
428	if_match_required	Perubahan memerlukan If-Match
429	rate_limited	Terlalu banyak panggilan; lihat Retry-After
502, 503	engine_refused, engine_unavailable	Mesin analitik perangkat sedang sibuk atau baru menyala; coba lagi nanti

Bangun integrasi Anda berdasarkan code, karena teks detail dapat berubah.

Konvensi

• Waktu memakai RFC 3339. Kirim periode sebagai from dan to dengan selisih zona waktu, misalnya from=2026-11-01T00:00:00%2B07:00. Angka per jam dan per hari mengikuti zona waktu lokasi.
• Daftar panjang dibagi per halaman: berikan limit, lalu next_before dari jawaban sebagai before untuk halaman berikutnya. next_before bernilai null di halaman terakhir.
• Perubahan yang dapat berbenturan membawa version (pengaturan) atau ETag yang dikirim kembali di If-Match (kamera dan gambarnya). Nilai yang usang ditolak, jadi baca lagi lalu ulangi.