Autentikasi

Cara membuat API key Chatera, memilih scope yang tepat, dan menjaganya tetap aman.

Setiap request ke API Chatera wajib menyertakan API key. Halaman ini menjelaskan tipe key, scope yang tersedia, dan cara mengirim key di header request.

Membuat API key

Hanya pengguna dengan role Owner atau Admin yang dapat membuat API key. Pengguna dengan role Agent tidak punya akses ke menu ini.

Buka Pengaturan > API & Integrasi

Dari dashboard app.chatera.id, pilih ikon roda gigi, lalu navigasi ke section API & Integrasi.

Klik "Buat API Key Baru"

Lengkapi form:

Nama — label untuk identifikasi (contoh: "Backend POS", "CRM Integrasi").
Tipe Key — Secret atau Publishable (lihat di bawah).
Izin Akses (Scope) — pilih hanya yang dibutuhkan integrasi kamu.

Setelah disimpan, key hanya ditampilkan satu kali. Salin dan simpan ke secret manager (mis. AWS Secrets Manager, Doppler, 1Password) sebelum menutup dialog. Key yang hilang tidak bisa diambil kembali — kamu harus membuat key baru.

Tipe key

Tipe	Prefix	Kegunaan
Secret Key	`chatera_sk_`	Akses penuh sesuai scope. Hanya untuk server-side.
Publishable Key	`chatera_pk_`	Akses terbatas, aman dipakai di aplikasi client (mobile, browser).

Jangan pakai Secret Key di frontend

chatera_sk_ tidak boleh masuk ke kode JavaScript yang dijalankan di browser, kode mobile yang di-bundle, atau repository public. Kalau kamu butuh dari aplikasi client, gunakan chatera_pk_ dengan scope minimum.

Scope yang tersedia

Pilih scope sesempit mungkin sesuai kebutuhan integrasi.

Scope	Akses
`contacts:read`	Membaca daftar dan detail kontak
`contacts:write`	Membuat dan mengubah kontak
`whatsapp:send`	Mengirim pesan WhatsApp (teks, media, lokasi, template, interaktif)
`whatsapp:read`	Membaca pesan dan percakapan
`whatsapp:templates`	Membaca daftar template WhatsApp
`webhooks:manage`	Membuat, mengubah, menghapus webhook

Mengirim key di request

Chatera menerima dua format header — pilih salah satu (jangan keduanya).

Opsi 1: `Authorization: Bearer` (rekomendasi)

GET /v1/contacts HTTP/1.1
Host: api.chatera.id
Authorization: Bearer chatera_sk_xxxxx

Opsi 2: `X-API-Key`

GET /v1/contacts HTTP/1.1
Host: api.chatera.id
X-API-Key: chatera_sk_xxxxx

Kedua format memberikan hasil identik.

Mencabut & merotasi key

Cabut key: dari dashboard, klik tombol "Cabut" di samping key. Key langsung tidak berlaku — request berikutnya akan menerima error AUTH_KEY_REVOKED.
Rotasi: praktek terbaik adalah membuat key baru, deploy ke produksi, lalu cabut key lama. Jangan gunakan key yang sama selama bertahun-tahun.
Audit: dashboard menampilkan timestamp last used at untuk setiap key. Key yang tidak pernah dipakai selama 90 hari sebaiknya dicabut.

Pesan error autentikasi

Kode	Pesan	Penyebab
`AUTH_MISSING_KEY`	API key tidak ditemukan	Header `Authorization` / `X-API-Key` tidak dikirim
`AUTH_INVALID_KEY`	API key tidak valid	Key salah ketik, ada karakter berlebih, atau prefix bukan `chatera_sk_` / `chatera_pk_`
`AUTH_KEY_REVOKED`	API key sudah dicabut	Key dicabut dari dashboard
`AUTH_KEY_EXPIRED`	API key sudah kadaluarsa	Key memiliki masa berlaku dan sudah lewat
`AUTH_INSUFFICIENT_SCOPE`	Tidak memiliki izin	Key tidak punya scope yang diperlukan endpoint

Best practice keamanan

Simpan key di environment variable atau secret manager — jangan hardcode.
Buat key terpisah per integrasi dan per environment (dev / staging / production).
Audit log setiap kali key dipakai (lihat header X-RateLimit-Remaining di response untuk memantau penggunaan).
Setiap orang baru yang join tim → buat key baru, jangan share key yang sudah ada.