Autentikasi

Setiap permintaan ke API Sursa membawa kunci API, atau token akses OAuth sebuah aplikasi, di header Authorization:

Authorization: Bearer kb_3f9c…

Kunci mengidentifikasi organisasi dan menentukan apa yang dapat dilihat dan diubah oleh permintaan: perannya, cakupannya, profil datanya, dan koleksinya. Tidak ada sesi atau cookie di alamat API. Setiap permintaan diautentikasi secara terpisah, jadi Anda dapat mengirim permintaan secara paralel dan dari beberapa server dengan kunci yang sama.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Integrasi lama mungkin mengirim kunci di header X-API-Key. Header itu masih diterima, tetapi kode baru sebaiknya memakai Authorization: Bearer.

Jenis kredensial

Kredensial	Bentuknya	Tempat berlakunya
Kunci API organisasi	`kb_…`	Setiap endpoint API, dalam batas peran, cakupan, profil data, dan koleksinya.
Kunci sumber kustom	`kbsrc_…`	Hanya endpoint push dari sumber kustom miliknya sendiri (`/v1/push/sources/{source_id}/…`).
Token akses OAuth	`kbat_…`	Endpoint di referensi API, dalam batas cakupan token. Token dari `POST /oauth/token` dengan kode otorisasi bertindak atas nama karyawan yang memberikan izin; token `client_credentials` bertindak untuk organisasi, seperti kunci API. Token berlaku selama 1 jam.

Semuanya dikirim dengan cara yang sama. Kunci sumber kustom tidak dapat membaca, mencari, atau mengubah apa pun di luar sumbernya; pakai kunci ini di tempat kunci disimpan oleh pihak ketiga, seperti platform integrasi.

Error autentikasi

Status dan kode	Artinya	Yang perlu dilakukan
`401` `auth.not_authenticated`	Tidak ada kunci, kunci salah ketik, atau kunci sudah dicabut.	Periksa header dan nilai kunci.
`401` `api_keys.expired`	Kunci sudah melewati tanggal kedaluwarsanya.	Buat kunci baru dan ganti kunci lama.
`401` `sources.push_key_invalid`	Kunci sumber kustom salah, sudah dicabut, atau milik sumber lain.	Periksa kunci dan ID sumber di path.
`401` `oauth.token_expired`	Token akses OAuth sudah kedaluwarsa.	Dapatkan token baru dengan token refresh.
`403` `api_keys.scope`	Kunci tidak memiliki cakupan untuk operasi ini.	Tambahkan cakupannya, atau pakai kunci yang memilikinya.
`403` `api_keys.feature_disabled`	Paket organisasi tidak mencakup kunci API.	Hubungi administrator organisasi.
`403` `api_keys.ip_not_allowed`	Permintaan datang dari alamat di luar alamat yang diizinkan untuk kunci.	Lakukan panggilan dari jaringan yang diizinkan, atau ubah alamat kunci.
`403` `api_keys.mcp_only`	Kunci MCP pribadi dipakai di luar endpoint `/mcp`.	Pakai kunci API organisasi untuk API.
`403` `oauth.operation_not_allowed`	Operasi ini bukan bagian dari API publik, jadi token OAuth tidak dapat memanggilnya.	Pakai operasi dari referensi API.
`403` `org.suspended`	Organisasi ditangguhkan. Datanya tetap disimpan.	Hubungi administrator organisasi.

403 berarti permintaan sudah diautentikasi tetapi tidak diizinkan. Objek yang tidak boleh dilihat oleh kunci menjawab 404, sama seperti objek yang tidak ada, jadi kunci tidak dapat mengetahui apa yang berada di luar aksesnya.

Bertindak sebagai profil data

Kunci dengan peran admin dapat memeriksa apa yang akan dilihat oleh kelompok orang lain: header X-View-As menjalankan permintaan sebagai profil data dan, jika perlu, sebagai peran tertentu.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Permintaan dalam mode ini hanya membaca: setiap perubahan mengembalikan 403 dengan kode view_as.read_only. Token OAuth, atau kunci tanpa peran admin, tidak dapat memakai X-View-As: jawabannya 403 dengan kode view_as.admin_key_required. Header yang tidak menyebut profil yang ada menjawab 400 dengan kode view_as.invalid_header.

Aplikasi peramban

API mengizinkan permintaan dari origin web mana pun (Access-Control-Allow-Origin: *) dan tidak pernah memakai cookie, jadi sebuah halaman dapat memanggilnya dengan fetch. Kuncinya lalu berada di halaman dan terlihat oleh siapa pun yang memakainya. Panggil API dari peramban hanya dengan kunci yang rela Anda tunjukkan kepada pengguna tersebut, seperti kunci viewer yang dibatasi pada koleksi publik, atau tempatkan server Anda sendiri di antara peramban dan Sursa.

Yang hanya dapat dilakukan karyawan

Kunci API organisasi bertindak untuk organisasi, bukan untuk seseorang. Dua bagian API milik orang, jadi keduanya hanya berfungsi dengan token yang bertindak atas nama karyawan: sesi di Sursa atau token akses OAuth yang diterbitkan dengan izin karyawan.

Percakapan milik seseorang. Di GET /v1/conversations, kunci API organisasi hanya melihat percakapan yang dimulainya sendiri. API publik tidak memiliki operasi yang memulai percakapan, jadi bagi kunci daftar ini biasanya kosong, dan percakapan karyawan tidak pernah ditampilkan kepadanya. Pertanyaan tanpa percakapan, dengan POST /v1/ask atau POST /v1/chat, berfungsi dengan kunci apa pun yang memiliki cakupan ask. Untuk menampilkan daftar percakapan seorang karyawan dan membaca riwayat salah satunya dengan GET /v1/conversations/{conv_id}, panggil API dengan token OAuth atas nama karyawan tersebut. Token hanya melihat percakapan milik karyawan itu sendiri; percakapan lain menjawab 404 dengan kode conversations.not_found.

Hanya karyawan yang memverifikasi kartu. Verifikasi menegaskan bahwa seseorang telah memeriksa isinya, jadi POST /v1/cards/{card_id}/verification/verify dan POST /v1/cards/{card_id}/verify memerlukan sesi atau token OAuth atas nama karyawan yang boleh memverifikasi kartu tersebut. Dengan kunci API organisasi, atau token client_credentials, keduanya menjawab 400 dengan kode cards.verify_user_account_required. Pemeriksaan biasa didahulukan: kartu yang tidak dapat dilihat oleh kunci menjawab 404, dan kunci yang tidak diizinkan memverifikasinya menjawab 403.