Token API

Token API adalah kunci rahasia dengan awalan kt_ yang dipakai sistem Anda untuk setiap permintaan. Token bertindak atas nama satu organisasi dan hanya bisa melakukan yang diizinkan saat dibuat.

Membuat token

Token hanya bisa dibuat oleh admin organisasi Anda di Kareeb.

1. Admin membuka menu Token API (grup Sistem), atau Pengaturan, bagian Integrasi & saluran.
2. Admin memberi nama token, misalnya nama sistem Anda, lalu memilih izinnya. Minimal satu izin.
3. Kareeb menampilkan token satu kali saja. Simpan saat itu juga di tempat penyimpanan rahasia sistem Anda.

Kareeb hanya menyimpan sidik (hash SHA-256) token, bukan teksnya, sehingga token tidak bisa ditampilkan lagi.

Mengirim token

Kirim token di header Authorization pada setiap permintaan:

Authorization: Bearer kt_xxxxxxxxxxxxxxxxxxxx

Jangan taruh token di URL

Token di alamat (?token=kt_...) ditolak dengan 403, karena alamat tercatat di log server dan di header Referer. Jangan bagikan token lewat grup chat atau email.

Token API hanya diterima di jalur yang ada di Referensi API. Token yang dikirim ke layar operator dijawab 403.

Izin dan artinya

Izin	Yang boleh dilakukan
read:contacts	Membaca kontak: GET /api/export/contacts dan GET /api/contacts/{id}
read:conversations	Membaca percakapan: GET /api/export/conversations
read:messages	Membaca pesan: GET /api/export/messages
read:campaigns	Membaca kampanye, corongnya, dan penerimanya: GET /api/export/campaigns, GET /api/export/campaign-stats, GET /api/export/campaigns/recipients
read:orders	Membaca pesanan: GET /api/export/orders
read:comments	Membaca komentar di unggahan sendiri: GET /api/export/komentar
read:templates	Membaca daftar template: GET /api/export/templates
send:broadcast	Mengirim satu template ke banyak nomor: POST /api/broadcasts
write:messages	Mengirim satu pesan ke satu pelanggan: POST /api/messages
write:suara	Meminta token panggilan suara untuk satu sesi aplikasi: POST /api/suara/token
write:pemantauan	Mengirim dan menghapus sebutan di halaman Pemantauan: POST /api/pemantauan/masuk, POST /api/pemantauan/hapus

Izin baca tidak bisa mengirim apa pun kepada siapa pun. Hanya empat izin yang menulis: send:broadcast, write:messages, write:suara, dan write:pemantauan. Izin write:pemantauan hanya menulis isi halaman Pemantauan, tanpa membuat kontak, percakapan, atau pesan.

Token yang tidak punya izin yang dibutuhkan dijawab 403 dengan nama izin yang kurang, misalnya:

{"detail": "Token API ini tidak punya izin read:contacts. Minta admin membuat token baru yang mencakup izin itu."}

Memeriksa token

GET /api/export/token menjawab organisasi dan izin token yang sedang dipakai. Endpoint ini tidak butuh izin khusus, cukup token yang masih aktif. Pakai saat sistem Anda pertama kali tersambung, supaya izin yang kurang ketahuan sebelum pengiriman pertama.

curl https://kareeb.id/api/export/token \
  -H "Authorization: Bearer kt_xxxxxxxxxxxxxxxxxxxx"

{
  "org_id": 1,
  "org_name": "Rumah Sakit Sentra",
  "token_id": 12,
  "scopes": ["write:messages", "read:templates"],
  "created_at": "2026-11-04T02:00:00+00:00"
}

Token itu sendiri, sidiknya, dan awalannya tidak pernah dikembalikan.

Cabang

Token API selalu berdiri di cabang Utama organisasi Anda. Akibatnya:

• daftar kontak, percakapan, kampanye, pesanan, dan komentar berisi data cabang Utama, sedangkan daftar pesan mencakup semua cabang;
• POST /api/broadcasts mengirim dari cabang Utama;
• POST /api/messages dan POST /api/suara/token bisa memilih cabang lain dengan workspace_id, asalkan cabang itu milik organisasi yang sama.

Token hilang atau bocor

Token yang hilang tidak bisa dipulihkan. Admin mencabut token lama di menu Token API, lalu membuat token baru dengan izin yang sama. Token yang dicabut langsung mati pada permintaan berikutnya:

{"detail": "Token API tidak dikenal atau sudah dicabut. Minta admin membuat token baru di Pengaturan."}

Token yang tidak dikenal dan token yang sudah dicabut dijawab sama (401), supaya jawaban tidak membocorkan token mana yang pernah ada.

Jawaban lain yang perlu dikenali

Kode	Arti
401	Tidak ada token, atau token tidak dikenal atau sudah dicabut.
402	Organisasi Anda sedang berstatus baca saja. Data masih bisa dibaca, tetapi pengiriman ditolak. Berhenti mengulang dan hubungi admin organisasi Anda.
403	Izin kurang, token dikirim di URL, atau organisasi sedang dinonaktifkan sementara oleh tim Kareeb.