Dasar

Autentikasi

Setiap permintaan wajib membawa API key milik aplikasi Anda pada header X-API-Key:

bash

export MASKI_API_KEY="mk_live_a1b2c3d4e5f6_..."

curl -s -H "X-API-Key: $MASKI_API_KEY" "https://api.maski.cloud/api/kjsb"

Kunci diterbitkan oleh pengelola MASKI lewat panel admin (Pengaturan → API Client). Yang perlu Anda ketahui saat menerimanya:

Kunci hanya ditampilkan sekali saat diterbitkan. MASKI menyimpan hash-nya, bukan kuncinya, jadi kunci yang hilang tidak bisa dilihat lagi — hanya bisa dirotasi.
Kunci mengidentifikasi APLIKASI, bukan orang. Ia tidak memberi akses ke data satu anggota tertentu, dan tidak bisa dipakai di /member atau /admin.
Jangan menaruhnya di kode yang berjalan di browser (JavaScript halaman, aplikasi mobile yang bisa dibongkar). Kunci di sisi klien sama dengan kunci publik. Panggil dari server Anda sendiri, lalu teruskan hasilnya.
Jangan mengirimnya lewat query string. Query string tercatat di access log dan header Referer; header X-API-Key tidak.
Kalau kunci bocor, mintalah rotasi. Pengelola bisa menerbitkan kunci baru dengan masa tenggang bagi kunci lama (sehingga tidak ada downtime), atau mencabut kunci lama seketika.

Scope

Tiap kunci diberi sekumpulan scope; endpoint yang di luar scope dibalas 403.

Scope	Memberi akses ke
kjsb:read	`GET /api/kjsb`, `GET /api/kjsb-summary`
sb:read	`GET /api/sb`
wilayah:read	`GET /api/wilayah/*`
branding:read	`GET /api/kjsb/{id}/branding`, `GET /api/kjsb/{id}/logo`
data:sensitif	Menyertakan `npwp` dan `latitude`/`longitude` pada response

Penting

data:sensitif sengaja dipisah: konsumen direktori umum tidak menerima NPWP maupun koordinat alamat sama sekali — field-nya tidak muncul di response, bukan bernilai null. Minta scope ini hanya bila aplikasi Anda memang membutuhkannya.

Batas pemakaian

Berlaku dua batas, keduanya per menit: 120 permintaan per API key dan 300 permintaan per alamat IP (angka default; pengelola dapat menyesuaikan per pemasangan). Melampauinya dibalas 429. Sisa kuota ada di header standar RateLimit-Limit, RateLimit-Remaining, dan RateLimit-Reset.

Bentuk response

Semua response memakai amplop yang sama:

json

{
  "status": true,
  "message": "success",
  "data": [ ... ],
  "pagination": {
    "count": 5,
    "total": 63,
    "per_page": 5,
    "current_page": 2,
    "total_pages": 13,
    "has_next": true
  }
}

Field	Arti
`status`	`true` bila berhasil, `false` bila gagal
`message`	`"success"`, atau pesan kesalahan yang bisa ditampilkan
`data`	array (endpoint daftar) atau objek (endpoint tunggal)
`pagination`	hanya ada pada endpoint daftar
`count`	jumlah baris di halaman ini
`total`	jumlah seluruh baris yang cocok dengan filter

Tip

Hanya anggota berstatus disetujui yang muncul. Pendaftaran yang masih diverifikasi atau ditolak tidak pernah ikut terdaftar.

Parameter bersama

Berlaku di semua endpoint daftar.

Parameter	Tipe	Default	Keterangan
`page`	integer > 0	`1`	Halaman ke berapa
`per_page`	integer > 0	`20`	Baris per halaman
`sort`	`ASC` \| `DESC`	`ASC`	Urutan berdasarkan nama. Huruf besar semua