API Documentation — License Manager

🔐

Autentikasi

API ini menggunakan dua metode autentikasi yang berbeda tergantung endpoint yang diakses. Pastikan Anda menggunakan key yang tepat untuk setiap jenis request.

⚠️ Jangan pernah menyimpan SUPER_ADMIN_KEY di sisi klien (browser/app). Key ini hanya boleh digunakan dari backend server.

Untuk Endpoint Admin

📋 HTTP Header

Header

x-api-key: YOUR_SUPER_ADMIN_KEY

Ganti YOUR_SUPER_ADMIN_KEY dengan master key yang dikonfigurasi di file .env server Anda. Key ini memberikan akses penuh ke seluruh operasi admin seperti membuat dan mengubah lisensi.

Untuk Endpoint Client

📋 Request Body

JSON

{
  "license_key": "PROD-XXXX-1234"
}

Endpoint client tidak memerlukan header khusus. Identifikasi dilakukan melalui license_key yang disertakan di body request.

🌐

Base URL

Semua endpoint menggunakan base URL berikut. Ubah sesuai environment Anda.

Development http://localhost:8000

Production https://your-domain.com

ℹ️ Seluruh contoh cURL di dokumentasi ini menggunakan base URL http://localhost:8000. Ganti dengan URL production saat deploy.

🛡️

Admin API — Buat Lisensi

Endpoint ini digunakan oleh admin untuk membuat lisensi baru. Setiap lisensi akan menghasilkan license key unik yang nantinya diberikan kepada pengguna atau pelanggan Anda.

POST http://localhost:8000/admin/licenses Create License

Membuat lisensi baru untuk suatu produk. Anda bisa mengatur apakah lisensi bersifat exclusive (hanya bisa digunakan di satu perangkat) atau tidak. Setelah dibuat, sistem akan mengembalikan license_key yang unik.

Headers Wajib

Header	Nilai	Keterangan
x-api-key WAJIB	string	Master key admin
Content-Type WAJIB	string	Harus bernilai `application/json`

Parameter Body (JSON)

Field	Tipe	Keterangan
product_name WAJIB	string	Nama produk yang akan dilisensi. Contoh: `"Premium App"`
exclusive_lock OPSIONAL	boolean	Jika `true`, lisensi hanya bisa diaktifkan di satu perangkat saja (terkunci ke device ID pertama yang mengaktifkannya). Jika `false` atau tidak diisi, lisensi bisa digunakan di banyak perangkat.

Contoh cURL — Lisensi Eksklusif (satu perangkat)

cURL

# Buat lisensi yang terkunci ke satu perangkat
curl -X POST http://localhost:8000/admin/licenses \
  -H "x-api-key: YOUR_SUPER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Premium App",
    "exclusive_lock": true
  }'

Contoh cURL — Lisensi Multi-Perangkat

cURL

# Buat lisensi yang bisa dipakai di banyak perangkat
curl -X POST http://localhost:8000/admin/licenses \
  -H "x-api-key: YOUR_SUPER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Team License",
    "exclusive_lock": false
  }'

Contoh Respons Sukses (200)

JSON Response

{
  "status": "success",
  "license_key": "PREMIUM-APP-A1B2-C3D4",
  "product_name": "Premium App",
  "exclusive_lock": true,
  "created_at": "2026-03-28T10:00:00Z"
}

Kemungkinan Error

Kode	Pesan	Penyebab
401	Unauthorized	API key salah atau tidak disertakan
400	Bad Request	Field `product_name` tidak diisi atau format JSON salah

✏️

Admin API — Update Lisensi

Mengubah properti lisensi yang sudah ada, seperti mengaktifkan/menonaktifkan lisensi, mengubah nama produk, atau mereset status perangkat yang terkunci.

PATCH http://localhost:8000/admin/licenses/{license_key} Update License

Perbarui detail lisensi berdasarkan license_key yang diberikan di URL path. Hanya field yang disertakan yang akan diperbarui (partial update).

Path Parameter

Parameter	Tipe	Keterangan
license_key WAJIB	string	License key target yang ingin diubah. Disertakan di URL, bukan di body.

Parameter Body (JSON) — Opsional semua, minimal 1

Field	Tipe	Keterangan
is_active OPSIONAL	boolean	Set `false` untuk menonaktifkan lisensi (memblokir akses)
product_name OPSIONAL	string	Ubah nama produk yang terasosiasi dengan lisensi ini
exclusive_lock OPSIONAL	boolean	Ubah mode kunci perangkat
reset_device OPSIONAL	boolean	Set `true` untuk mereset device yang terkunci, memungkinkan aktivasi ulang di perangkat baru

Contoh cURL — Nonaktifkan Lisensi

cURL

# Nonaktifkan lisensi tertentu
curl -X PATCH http://localhost:8000/admin/licenses/PREMIUM-APP-A1B2-C3D4 \
  -H "x-api-key: YOUR_SUPER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Contoh cURL — Reset Device Lock

cURL

# Reset perangkat yang terkunci agar bisa aktivasi di device baru
curl -X PATCH http://localhost:8000/admin/licenses/PREMIUM-APP-A1B2-C3D4 \
  -H "x-api-key: YOUR_SUPER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reset_device": true
  }'

Contoh Respons Sukses (200)

JSON Response

{
  "status": "updated",
  "license_key": "PREMIUM-APP-A1B2-C3D4",
  "is_active": false
}

⚡

Client API — Aktivasi Lisensi

Digunakan oleh aplikasi klien untuk mengklaim lisensi ke perangkat pengguna. Ini adalah langkah pertama yang harus dilakukan sebelum bisa menggunakan heartbeat.

ℹ️ Alur penggunaan: Aktivasi dilakukan sekali saat instalasi/login pertama. Setelah berhasil, simpan license_key dan device_id secara lokal untuk digunakan pada heartbeat berikutnya.

1 Pengguna masukkan license key

→

2 App kirim request aktivasi

→

3 Server validasi & kunci device

→

4 Akses diberikan

POST http://localhost:8000/client/activate Activate License

Mengklaim lisensi untuk perangkat tertentu menggunakan device_id. Jika lisensi bersifat exclusive, device ID pertama yang berhasil aktivasi akan "mengunci" lisensi tersebut.

Parameter Body (JSON)

Field	Tipe	Keterangan
license_key WAJIB	string	License key yang diberikan ke pengguna. Contoh: `"PROD-ABCD-1234"`
device_id WAJIB	string	ID unik perangkat pengguna (hardware ID, UUID, MAC address, dsb). Digunakan untuk mengidentifikasi perangkat.
device_name OPSIONAL	string	Nama perangkat yang mudah dibaca, untuk keperluan monitoring di dashboard admin. Contoh: `"User-PC"`

Contoh cURL — Aktivasi Lisensi

cURL

# Aktivasi lisensi untuk perangkat tertentu
curl -X POST http://localhost:8000/client/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "PROD-ABCD-1234",
    "device_id": "HW-9988-77",
    "device_name": "Laptop Kantor Budi"
  }'

Contoh Respons Sukses (200)

JSON Response

{
  "status": "activated",
  "license_key": "PROD-ABCD-1234",
  "device_id": "HW-9988-77",
  "product_name": "Premium App",
  "activated_at": "2026-03-28T10:05:00Z"
}

Kemungkinan Error

Kode	Pesan	Penyebab
400	Bad Request	Field wajib tidak disertakan
401	License not found	License key tidak ditemukan di sistem
409	Device mismatch	Lisensi sudah terkunci ke perangkat lain (exclusive lock)

💓

Client API — Heartbeat

Heartbeat adalah sinyal periodik yang dikirim aplikasi klien untuk membuktikan bahwa sesi lisensi masih aktif. Jika tidak ada heartbeat dalam jangka waktu tertentu, server dapat menganggap sesi tersebut telah berakhir.

💡 Rekomendasi: Kirim heartbeat setiap 60 detik dari background thread/worker. Jangan kirim dari UI thread agar tidak memblok antarmuka pengguna.

⚠️ Pastikan sudah melakukan aktivasi terlebih dahulu sebelum mengirim heartbeat. Heartbeat dari device yang belum teraktivasi akan ditolak.

POST http://localhost:8000/client/heartbeat Send Heartbeat

Menjaga sesi lisensi tetap aktif. Request ini memperbarui timestamp terakhir aktivitas dari perangkat yang bersangkutan. Server menggunakan data ini untuk monitoring penggunaan lisensi secara real-time.

Parameter Body (JSON)

Field	Tipe	Keterangan
license_key WAJIB	string	License key yang sama dengan yang digunakan saat aktivasi
device_id WAJIB	string	Device ID yang sama dengan yang digunakan saat aktivasi. Harus cocok persis.

Contoh cURL — Kirim Heartbeat

cURL

# Kirim heartbeat setiap 60 detik
curl -X POST http://localhost:8000/client/heartbeat \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "PROD-ABCD-1234",
    "device_id": "HW-9988-77"
  }'

Contoh Script — Loop Heartbeat (Bash)

Bash Script

#!/bin/bash
# Jalankan heartbeat terus-menerus setiap 60 detik

LICENSE_KEY="PROD-ABCD-1234"
DEVICE_ID="HW-9988-77"
API_URL="http://localhost:8000/client/heartbeat"

while true; do
  curl -X POST "$API_URL" \
    -H "Content-Type: application/json" \
    -d "{\"license_key\": \"$LICENSE_KEY\", \"device_id\": \"$DEVICE_ID\"}" \
    --silent
  echo "Heartbeat sent at $(date)"
  sleep 60
done

Contoh Respons Sukses (200)

JSON Response

{
  "status": "ok",
  "last_seen": "2026-03-28T10:06:00Z",
  "next_required_by": "2026-03-28T10:07:00Z"
}

Kemungkinan Error

Kode	Pesan	Penyebab
401	License not found	License key tidak valid
409	Device mismatch	Device ID tidak cocok dengan yang tersimpan di server
400	License inactive	Lisensi telah dinonaktifkan oleh admin

📊

Referensi Kode Respons

Semua endpoint menggunakan kode HTTP standar. Berikut ringkasannya:

Kode	Nama	Arti
200	OK / Success	Request berhasil diproses
400	Bad Request	Format request salah atau field wajib tidak ada
401	Unauthorized	API key salah, license key tidak ditemukan, atau tidak memiliki izin
409	Conflict	Konflik data — misalnya lisensi sudah terkunci ke device lain
500	Server Error	Kesalahan internal server, coba lagi atau hubungi developer

API License Manager

Autentikasi

Base URL

Admin API — Buat Lisensi

Admin API — Update Lisensi

Client API — Aktivasi Lisensi

Client API — Heartbeat

Referensi Kode Respons