Kunci API dan cakupan

Setiap permintaan ke API Sursa dikirim dengan kunci API organisasi Anda. Kunci adalah milik organisasi, bukan milik seseorang: kunci tetap berfungsi saat karyawan yang membuatnya keluar, dan apa yang dapat dilakukannya diatur pada kunci itu sendiri.

Apa yang boleh dilakukan sebuah kunci

Tiga pengaturan kunci menentukan apa yang dapat dilihat dan diubah oleh permintaan dengan kunci itu. Masing-masing hanya mempersempit yang lain.

Kunci juga dapat dibatasi pada beberapa koleksi dan diberi tanggal kedaluwarsa. Permintaan di luar batas ini gagal: cakupan yang tidak ada mengembalikan 403 dengan kode api_keys.scope, dan objek yang tidak dapat dilihat kunci mengembalikan 404, persis seolah-olah objek itu tidak ada.

Berikan setiap integrasi kuncinya sendiri dengan peran dan cakupan tersempit yang dibutuhkannya. Job sinkronisasi yang hanya menulis dokumen tidak membutuhkan admin; job pelaporan tidak membutuhkan cakupan tulis.

Membuat kunci

Administrator organisasi membuat kunci di Sursa melalui Administration → API keys (Administrasi → Kunci API), atau dengan POST /v1/api-keys memakai kunci atau sesi yang memiliki peran admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Respons berisi nilai kunci di key. Nilai itu ditampilkan sekali: Sursa hanya menyimpan hash-nya dan tidak dapat menampilkannya lagi. Kunci berbentuk kb_ diikuti 43 karakter; karakter pertamanya (prefix) ditampilkan di daftar kunci agar Anda dapat membedakan kunci-kunci itu.

Tanpa scopes, kunci mendapat cakupan perannya. Berikan scopes untuk mempersempitnya lebih jauh. Tanpa expires_at, kunci tidak kedaluwarsa.

Menjaga kerahasiaan kunci

• Simpan kunci di pengelola rahasia atau di variabel lingkungan layanan Anda, jangan pernah di kode sumber.
• Pakai kunci hanya dari server Anda. Sursa menerima permintaan dari peramban (CORS terbuka), tetapi kunci di halaman web terlihat oleh semua orang yang membukanya.
• Jangan pernah mengirim kunci di URL. Kirim kunci hanya di header Authorization.
• Jika kunci bocor, segera cabut dan buat kunci baru.

Memeriksa kunci

GET /v1/me mengembalikan kunci, perannya, cakupan efektif, profil data, tanggal kedaluwarsa, dan batas lajunya. Endpoint ini berfungsi dengan kunci valid apa pun, apa pun cakupannya, jadi pakai endpoint ini sebagai uji koneksi integrasi Anda dan saat Anda menyelidiki 403.

Merotasi kunci

Rotasi mengganti kunci tanpa menghentikan integrasi. Cara tercepat adalah menerbitkan ulang kunci: POST /v1/api-keys/{key_id}/roll menerbitkan nilai baru untuk kunci yang sama, dengan peran, cakupan, koleksi, dan tanggal kedaluwarsa yang sama. Nilai sebelumnya tetap berfungsi selama overlap_hours (default 24 jam, hingga 168), jadi Anda dapat memasang nilai baru dalam waktu itu; POST /v1/api-keys/{key_id}/revoke-previous mengakhiri masa tumpang tindih lebih awal.

Untuk mengganti kunci dengan kunci lain:

1. Buat kunci baru dengan peran, cakupan, dan profil data yang sama.
2. Pasang kunci baru di integrasi Anda.
3. Pantau kunci lama di Administration → API keys (atau last_used di GET /v1/api-keys) hingga kunci itu tidak dipakai lagi.
4. Cabut kunci lama.

Tetapkan tanggal kedaluwarsa pada kunci dan rotasi kunci sebelum tanggal itu. Sursa memperingatkan administrator organisasi sebelum kunci kedaluwarsa; kunci yang sudah kedaluwarsa mengembalikan 401 dengan kode api_keys.expired.

Mencabut kunci

Cabut kunci di Administration → API keys atau dengan DELETE /v1/api-keys/{key_id}. Pencabutan berlaku dalam hitungan detik di setiap server API. Permintaan dengan kunci yang sudah dicabut mengembalikan 401 dengan kode auth.not_authenticated.

Kunci sumber kustom

Sumber kustom memiliki jenis kuncinya sendiri. Kunci ini diawali kbsrc_, hanya dapat menulis dokumen ke satu sumber itu, dan tidak dapat membaca atau mencari apa pun. Inilah kunci paling aman untuk diberikan kepada platform integrasi seperti Zapier. Buat kunci ini di halaman sumber melalui API keys (kunci API sumber) atau dengan POST /v1/sources/{source_id}/push-keys.

Saat kunci tidak tersedia

Kunci API adalah bagian dari paket organisasi. Jika paket tidak mencakupnya, pembuatan kunci dan setiap permintaan dengan kunci mengembalikan 403 dengan kode api_keys.feature_disabled.