Autentikasi

API mengautentikasi server dengan kunci API organisasi. Sebuah kunci dimiliki oleh organisasi (bukan oleh perorangan), membawa sekumpulan izin, dan bekerja tepat dalam satu mode: uji atau live.

Mengirim kunci

Gunakan salah satu header berikut:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

Kunci berbentuk bf_live_… atau bf_test_…. Kunci yang tidak ada menghasilkan 401 (unauthorized); kunci yang formatnya salah, dicabut, atau kedaluwarsa juga menghasilkan 401. Simpan kunci di server Anda: jangan pernah mengirimkannya ke browser atau aplikasi seluler. Untuk penandatanganan di browser, buatlah sesi penandatanganan sebagai gantinya.

Kunci uji dan live

	Uji (`bf_test_…`)	Live (`bf_live_…`)
Dokumen	Dirender dengan tanda air `TEST`	Bersih
Email	Hanya dikirim ke anggota organisasi Anda	Dikirim ke setiap penerima
Penagihan	Gratis dan tanpa batas, tidak pernah dihitung	Amplop yang selesai dihitung dalam kuota paket Anda
Data	Amplop, tautan, dan endpoint webhook yang dibuat dengan kunci ini berada dalam mode uji	Mode live

Mode berasal dari kunci, bukan dari permintaan: ?test_mode=true pada POST /v1/envelopes hanya berlaku untuk sesi dasbor. Daftar (GET /v1/envelopes, GET /v1/signing-links) hanya mengembalikan data dalam mode kunci tersebut, dan event sebuah amplop hanya dikirim ke endpoint webhook dengan mode yang sama. Setiap amplop dan payload webhook menyebutkan modenya (testMode).

Membuat dan mencabut kunci

Kunci dikelola di dasbor, Pengaturan › Kunci API, oleh anggota yang memiliki izin apikey:manage (pemilik dan admin). Secret ditampilkan sekali, saat kunci dibuat. Anda dapat memberi kunci nama, mode, masa berlaku (1 hingga 365 hari, atau tanpa batas), dan scope.

Scope

Scope sebuah kunci adalah izin organisasi yang boleh digunakannya. Secara default, kunci baru mendapat izin pembuatnya dikurangi izin administratif (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), dan tidak ada yang dapat memberi kunci izin yang tidak dimilikinya sendiri. Panggilan di luar scope kunci menghasilkan 403 yang menyebutkan izin yang kurang:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Izin	Mengizinkan kunci untuk
`template:read`	Menampilkan daftar dan membaca template, versi, dan PDF-nya
`template:write`	Membuat template, mengunggah file, menyimpan draf, menghapus template yang tidak terpakai
`template:publish`	Memublikasikan draf sebagai versi baru
`envelope:read`	Menampilkan daftar dan membaca amplop, dokumen, dan jejak audit; menampilkan daftar tautan penandatanganan
`envelope:send`	Membuat amplop, sesi penandatanganan, dan tautan penandatanganan; mengirim ulang tautan
`envelope:void`	Membatalkan amplop yang sedang berjalan
`org:manage`	Mengelola endpoint webhook dan mengirim ulang event; membaca pengaturan organisasi
`billing:manage`	Membaca pemakaian (`GET /v1/usage`) dan jumlah tagihan

Mengelola endpoint webhook memerlukan org:manage, yang secara default tidak diberikan ke kunci: daftarkan endpoint di dasbor, atau buat kunci dengan scope tersebut secara eksplisit.

Endpoint dan jenis autentikasinya

Setiap operasi di referensi API mencantumkan skema keamanannya. Singkatnya:

Kunci API atau sesi dasbor: template, amplop, sesi penandatanganan, tautan penandatanganan, endpoint webhook, pengaturan organisasi, ringkasan penagihan, dan pemakaian.
Hanya sesi dasbor: kunci API, token SCIM, pengaturan koneksi SSO, unggah logo organisasi, checkout dan portal penagihan, menampilkan secret webhook.
Token penanda tangan: /v1/signing/*, digunakan oleh halaman yang di-hosting dan <bf-signing> dengan token sesi (bfs_…) atau token akses hasil penukarannya (bfa_…).
Publik: /v1/links/{id} (tautan yang selalu aktif), /v1/sso/discover, dan API verifikasi (/v1/public/*, /.well-known/bona-fide/keys.json).

Masuk ke dasbor

Orang (bukan server) masuk ke dasbor di https://app.bonafidesign.com/sign-in. Cara default adalah email dan kata sandi; alternatifnya adalah kode enam digit yang dikirim lewat email (Kirimkan kode ke email saya), magic link, passkey, Google atau Microsoft, dan SSO perusahaan Anda.

Membuat akun dengan kata sandi mengirim satu email: kode yang mengonfirmasi bahwa alamat tersebut milik Anda. Sebelum itu, kata sandi belum bisa dipakai untuk masuk. Mendaftar dengan alamat yang sudah memiliki akun tidak mengubah apa pun dan dijawab persis seperti pendaftaran baru; pemilik alamat tersebut mendapat email yang menjelaskan cara masuk.
Kata sandi terdiri dari 12 hingga 128 karakter dan disimpan sebagai hash scrypt dengan salt. Kata sandi baru yang muncul dalam kebocoran data yang diketahui akan ditolak: hanya lima karakter pertama dari hash SHA-1-nya yang dikirim ke Have I Been Pwned (k-anonimitas), tidak pernah kata sandinya. Jika layanan tersebut tidak menjawab dalam dua detik, kata sandi diterima tanpa pemeriksaan.
Lupa kata sandi? Email reset berisi tautan ke halaman tempat Anda memilih kata sandi baru. Tautan hanya berfungsi sekali dan kedaluwarsa setelah satu jam, dan menggunakannya akan mengeluarkan Anda dari semua perangkat.
Belum punya kata sandi? Akun yang dibuat dengan kode, tautan, passkey, atau Google / Microsoft tetap masuk dengan cara itu, dan dapat menambahkan kata sandi di Pengaturan › Akun. Menetapkan kata sandi pertama memerlukan proses masuk dalam 15 menit terakhir (halaman akan mengirim kode lewat email untuk memastikan itu Anda); mengubahnya memerlukan kata sandi saat ini. Keduanya mengeluarkan sesi Anda yang lain.
Error tidak pernah mengungkap akun: kata sandi yang salah, alamat yang tidak dikenal, dan akun tanpa kata sandi mendapat jawaban yang sama, dan permintaan reset selalu menyatakan bahwa email sedang dikirim.
Batas laju: permintaan masuk dengan kata sandi, pendaftaran, dan reset dibatasi per alamat IP dan per alamat email; setelah batas terlampaui, jawabannya 429 hingga jendela waktunya berlalu.
SSO perusahaan: saat organisasi Anda mewajibkan SSO, anggota dengan domain email organisasi hanya dapat masuk melalui penyedia identitas. Kata sandi, kode, dan magic link ditolak untuk mereka; pemilik tetap memiliki kode email sebagai akses darurat.

Id permintaan

Setiap respons membawa header x-request-id, dan setiap body error membawa requestId. Anda dapat mengirim x-request-id sendiri (8 hingga 128 karakter dari A-Z a-z 0-9 . _ -) untuk mengorelasikan log; jika tidak, API akan membuatnya. Sertakan id ini saat menghubungi tim dukungan.