Cakupan kunci

Cakupan menyebutkan bagian API yang boleh dipanggil oleh sebuah kunci. Setiap endpoint di referensi API menyatakan satu cakupan yang dibutuhkannya. Permintaan dengan kunci yang tidak memiliki cakupan itu ditolak dengan 403 dan kode api_keys.scope, sebelum apa pun dibaca atau diubah.

Cakupan menentukan operasi mana yang boleh dipanggil kunci. Peran, profil data, dan koleksi kunci tetap menentukan objek mana yang dilihat oleh operasi itu: kunci dengan cards:write dan peran viewer tidak dapat mengubah kartu, dan kunci yang dibatasi pada satu koleksi tidak melihat koleksi lain.

Cakupan

Cakupan	Mengizinkan
`cards:read`	Membaca kartu, koleksi, dan folder.
`cards:write`	Membuat, mengubah, dan menghapus kartu, koleksi, dan folder.
`search`	Mencari di basis pengetahuan (`POST /v1/search`).
`ask`	Bertanya kepada asisten (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Menulis ke sumber kustom organisasi: sinkronisasi, batch, dan penghapusan, serta membaca statusnya. Membuat sumber dan kuncinya memerlukan `admin`.
`webhooks:manage`	Mengelola webhook dan membaca umpan peristiwa (`GET /v1/webhook-events`). Keduanya juga memerlukan peran `admin`.
`users:read`	Membaca pengguna dan grup.
`users:write`	Mengubah pengguna dan grup.
`analytics:read`	Membaca analitik.
`audit:read`	Membaca log audit.
`finance:read`	Membaca laporan keuangan, faktur, dan pembayaran.
`catalog:read`	Membaca katalog layanan.
`files:read`	Membaca file yang dihasilkan, seperti jawaban yang diekspor.
`files:write`	Mengubah dan menghapus file yang dihasilkan.
`permissions:manage`	Memberikan dan mencabut izin pada objek.
`admin`	Pengaturan organisasi dan kunci API-nya. Kunci dengan `admin` juga memiliki semua cakupan lainnya.

Pencarian dan pertanyaan pada dasarnya adalah operasi baca: kunci yang hanya boleh membaca tetap dapat mencari dan bertanya.

Memilih cakupan

Berikan cakupan yang dipakai integrasi dan tidak lebih:

Integrasi	Cakupan
Bot tanya jawab di alat chat	`search`, `ask`
Impor dari sistem dokumen Anda	`cards:write` (API kartu) atau `import:write` (sumber kustom)
Ekspor ke gudang data	`cards:read`, `users:read`, dan `webhooks:manage` untuk umpan peristiwa
Penyediaan pengguna dari sistem HR Anda	`users:write`

Berikan daftarnya saat Anda membuat kunci:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

Cakupan lama

Kunci yang dibuat sebelum cakupan dipecah tetap berfungsi. Cakupan read, write, dan admin miliknya mewakili kumpulan berikut:

Cakupan lama	Artinya
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	semua yang ada di `read`, ditambah `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	semua cakupan

Kunci yang dibuat tanpa cakupan eksplisit mendapat cakupan dari perannya: admin mendapat admin; editor dan verifier mendapat write; viewer mendapat read.

Melihat cakupan sebuah kunci

GET /v1/me mengembalikan cakupan kunci yang mengirim permintaan, apa pun cakupan yang dimilikinya. Untuk kunci yang dibuat tanpa cakupan eksplisit, cakupan ini adalah cakupan lama dari perannya, seperti read dan write; tabel di atas menunjukkan artinya. Jika operasi gagal dengan api_keys.scope, error.message menyebutkan cakupan yang tidak ada.