Autentikasi

FreeMaint menerima dua mekanisme autentikasi: JWT (diterbitkan oleh /auth/login, digunakan oleh aplikasi web dan seluler kami) dan kunci API (dibuat di /company-settings/api, digunakan oleh integrasi Anda sendiri).

JWT (sesi pengguna)

1. POST /auth/login — Body: {email, password}. Mengembalikan {access_token, refresh_token}.
2. Kirim header Authorization — Pada setiap permintaan: Authorization: Bearer <access_token>.
3. Refresh saat kedaluwarsa — POST /auth/refresh dengan refresh_token untuk mendapatkan access_token baru. Token akses berlaku 2 jam.

Kunci API (integrasi server)

1. Buka /company-settings/api atau /profile/api-keys — Admin membuat kunci di Pengaturan Perusahaan > API, mulai dari paket Business ke atas. Orang yang perannya memiliki izin “Membuat kunci API pribadi” membuat kuncinya sendiri di Profil > Keamanan > Kunci API. Peran dengan izin "Mengelola integrasi" (misalnya templat Administrator integrasi) dapat membuat, mencabut, dan menghapus kunci perusahaan tanpa menjadi admin; hanya admin yang dapat menyerahkan kunci kepada orang lain.
2. Klik 'Kunci baru' — Secara opsional atur masa kedaluwarsa dan tingkat akses (Hanya baca secara bawaan). Kunci mentah hanya ditampilkan SEKALI — segera salin.
3. Gunakan — Kirim Authorization: Bearer fmk_<rawKey> pada setiap permintaan. Format: dimulai dengan fmk_ diikuti 32 karakter heksadesimal.

Catatan keamanan

• Kunci API disimpan sebagai hash SHA-256 — setelah Anda menutup dialog reveal, nilai mentahnya tidak dapat dipulihkan
• Mencabut kunci akan langsung menonaktifkannya; baris data disimpan untuk audit
• Setiap kunci milik satu perusahaan saja dan hanya menjangkau data perusahaan tersebut — catatan milik perusahaan lain dianggap tidak ditemukan
• Kunci dapat memiliki expiresAt opsional untuk integrasi berumur pendek
• Tingkat akses, batas atas di atas izin pemilik: READ (bawaan — hanya kueri), READ_STOCK (kueri + adjustStock — ideal untuk kios khusus pemakaian), FULL (semua operasi yang diizinkan peran pemilik)
• Setiap kunci bertindak sebagai pemiliknya: setiap panggilan membawa izin dan visibilitas data pemiliknya, dan apa yang ditulis kunci ditandatangani dengan nama pemiliknya. Jika pemilik dinonaktifkan, kunci ditolak (401, kode API_KEY_OWNER_INACTIVE) sampai admin menyerahkannya kepada orang lain di Pengaturan Perusahaan > API — nilai kunci tidak berubah.

Menguji integrasi

Tidak ada lingkungan sandbox terpisah: kunci API selalu mengakses data nyata perusahaan pemiliknya. Ada dua cara menguji dengan aman. (1) Gunakan perusahaan kedua sebagai perusahaan uji — isolasi antarperusahaan adalah mekanisme yang sama yang memisahkan setiap pelanggan, jadi apa pun yang Anda lakukan di sana tidak dapat menjangkau data produksi Anda. Kunci API memerlukan paket Business, jadi perusahaan itu juga harus berada di paket Business: perusahaan gratis tidak dapat membuatnya. (2) Untuk pekerjaan baca saja, buat kunci dengan tingkat akses READ: kunci ini menjalankan semua kueri dan tidak satu pun mutasi, sehingga sama sekali tidak dapat mengubah apa pun. Ketika siap menulis, kunci READ_STOCK hanya mengizinkan adjustStock.