Autentikasi

Kunci API (disarankan untuk integrasi)

Kunci API adalah token akses pribadi yang terikat pada seorang anggota akun Anda.

• Buat kunci di Pengaturan → Plugin → Kunci API RolChat. Secret ditampilkan sekali; setelah itu hanya sepuluh karakter pertamanya yang terlihat, dan RolChat hanya menyimpan hash SHA-256.
• Format: rcp_ diikuti 32 byte acak dalam base64url, total sekitar 45 karakter. Prefiks membuat kunci mudah dikenali di log dan berbeda dari token sesi.
• Scope: dipilih dari katalog kemampuan tetap saat kunci dibuat. Kunci tidak pernah dapat melakukan lebih dari anggota yang membuatnya: pada setiap panggilan kedua syarat diperiksa, kemampuan ada di scope kunci dan anggota masih memilikinya. Persempit peran anggota, dan kunci ikut menyempit.
• Masa berlaku: kunci tidak kedaluwarsa dengan sendirinya. Cabut kunci dari halaman profil atau dengan DELETE /api/v1/tokens/:id; pencabutan berlaku seketika. Tidak ada rotasi di tempat: cabut dan buat kunci baru.
• Pembuatan dan pencabutan dicatat di log audit.

Kirim sebagai bearer token - tidak ada header kunci API tersendiri:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Permintaan dengan kunci API plugin dibatasi 300 per menit.

Sesi JWT

Aplikasi web dan SDK seluler login dengan email dan kata sandi (atau Google atau Apple) dan menerima sepasang token.

Token	Masa berlaku	Catatan
Access token	15 menit	RS256, diverifikasi terhadap JWKS di /.well-known/jwks.json
Refresh token	30 hari	Dirotasi pada setiap refresh; penggunaan ulang token yang sudah dirotasi mencabut seluruh rantai

Claim: sub (pengguna), acc (akun), rl (peran), dan untuk peran per situs, sts (situs yang diizinkan).

POST /auth/login, /auth/refresh, /auth/swap-company, dan /auth/logout adalah satu-satunya endpoint alur autentikasi yang tidak boleh membawa header X-Account-Id yang dijelaskan berikutnya.

Header X-Account-Id

Setiap permintaan terautentikasi selain empat di atas harus membawa akun yang menjadi sasaran tindakannya:

X-Account-Id: <account uuid>

Server memeriksa bahwa header sama dengan claim acc pada token (atau akun pemilik kunci API). Header yang tidak ada menghasilkan 400 missing_required_header; ketidakcocokan menghasilkan 403 account_context_mismatch. Header ini ada agar bug di klien atau token yang diputar ulang tidak pernah dapat membaca data tenant lain secara diam-diam: ketidakcocokan ditolak sebelum kueri apa pun dijalankan, dan setiap baris log dapat diatribusikan ke akun tanpa mendekode token.

Pengguna multi-perusahaan

Satu orang dapat menjadi anggota beberapa perusahaan. Setiap perusahaan memiliki token sendiri (claim acc sendiri). Untuk beralih:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

Target harus salah satu dari available_companies milik pemanggil (dikembalikan saat login), jika tidak 403 forbidden. Responsnya adalah pasangan access dan refresh token baru yang dibatasi ke target; refresh token lama dicabut dan event audit auth.account.swapped ditulis.

Autentikasi multi-faktor

MFA berbasis TOTP dapat didaftarkan per anggota dan diwajibkan per akun. Saat aktif, POST /auth/login mengembalikan tantangan dan sesi diselesaikan dengan POST /auth/mfa/verify. Kode cadangan diterbitkan saat pendaftaran.

Perlindungan login

• Rute login dibatasi 10 percobaan per IP per menit dan 5 per email per 15 menit.
• Sepuluh kali login gagal mengunci email selama 30 menit; responsnya membawa code: account_locked.
• reCAPTCHA dapat diaktifkan per tindakan (pendaftaran, login, reset kata sandi); konfigurasi awal publik disajikan dari GET /api/v1/captcha.