Xác thực

API xác thực máy chủ bằng khóa API của tổ chức. Một khóa thuộc về một tổ chức (không thuộc về một cá nhân), mang một tập quyền, và hoạt động ở đúng một chế độ: thử nghiệm hoặc trực tiếp.

Gửi khóa

Dùng một trong hai header:

# 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_…"

Khóa có dạng bf_live_… hoặc bf_test_…. Thiếu khóa sẽ trả về 401 (unauthorized); khóa sai định dạng, đã thu hồi hoặc đã hết hạn cũng trả về 401. Hãy giữ khóa trên máy chủ: không bao giờ đưa khóa vào trình duyệt hay ứng dụng di động. Để ký trong trình duyệt, hãy tạo một phiên ký thay thế.

Khóa thử nghiệm và khóa trực tiếp

	Thử nghiệm (`bf_test_…`)	Trực tiếp (`bf_live_…`)
Tài liệu	Được kết xuất với hình mờ `TEST`	Không có hình mờ
Email	Chỉ gửi đến thành viên trong tổ chức của bạn	Gửi đến mọi người nhận
Tính phí	Miễn phí và không giới hạn, không bao giờ được tính	Phong bì đã hoàn tất được tính vào gói của bạn
Dữ liệu	Phong bì, liên kết và endpoint webhook được tạo bằng khóa này thuộc chế độ thử nghiệm	Chế độ trực tiếp

Chế độ được xác định bởi khóa, không bao giờ bởi yêu cầu: ?test_mode=true trên POST /v1/envelopes chỉ áp dụng cho phiên bảng điều khiển. Các danh sách (GET /v1/envelopes, GET /v1/signing-links) chỉ trả về dữ liệu thuộc chế độ của khóa, và sự kiện của một phong bì chỉ được gửi đến endpoint webhook cùng chế độ. Mọi phong bì và payload webhook đều cho biết nó thuộc chế độ nào (testMode).

Tạo và thu hồi khóa

Khóa được quản lý trong bảng điều khiển, tại Settings › API keys, bởi những thành viên có quyền apikey:manage (chủ sở hữu và quản trị viên). Secret chỉ hiển thị một lần, khi khóa được tạo. Bạn có thể đặt cho khóa một tên, một chế độ, thời hạn (từ 1 đến 365 ngày, hoặc không có) và phạm vi quyền.

Phạm vi quyền

Phạm vi quyền của một khóa là các quyền của tổ chức mà khóa được phép dùng. Theo mặc định, khóa mới nhận các quyền của người tạo, trừ các quyền quản trị (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), và không ai có thể cấp cho khóa một quyền mà chính họ không có. Một lệnh gọi nằm ngoài phạm vi quyền của khóa sẽ trả về 403 kèm tên quyền còn thiếu:

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

Quyền	Cho phép khóa
`template:read`	Liệt kê và đọc mẫu, phiên bản và tệp PDF của chúng
`template:write`	Tạo mẫu, tải tệp lên, lưu bản nháp, xóa các mẫu chưa dùng
`template:publish`	Xuất bản bản nháp thành phiên bản mới
`envelope:read`	Liệt kê và đọc phong bì, tài liệu và nhật ký kiểm tra; liệt kê liên kết ký
`envelope:send`	Tạo phong bì, phiên ký và liên kết ký; gửi lại liên kết
`envelope:void`	Hủy phong bì đang xử lý
`org:manage`	Quản lý endpoint webhook và gửi lại sự kiện; đọc cài đặt của tổ chức
`billing:manage`	Đọc mức sử dụng (`GET /v1/usage`) và số tiền trên hóa đơn

Việc quản lý endpoint webhook cần org:manage, quyền mà khóa không được cấp theo mặc định: hãy đăng ký endpoint trong bảng điều khiển, hoặc tạo một khóa có phạm vi quyền đó một cách tường minh.

Endpoint nào chấp nhận phương thức nào

Mỗi thao tác trong tài liệu tham khảo API đều liệt kê các cơ chế bảo mật của nó. Tóm lại:

Khóa API hoặc phiên bảng điều khiển: mẫu, phong bì, phiên ký, liên kết ký, endpoint webhook, cài đặt tổ chức, tổng quan tính phí và mức sử dụng.
Chỉ phiên bảng điều khiển: khóa API, token SCIM, cài đặt kết nối SSO, tải lên logo tổ chức, trang thanh toán và cổng quản lý tính phí, hiển thị secret của webhook.
Token người ký: /v1/signing/*, được trang lưu trữ sẵn và <bf-signing> sử dụng với token phiên (bfs_…) hoặc token truy cập được đổi từ token đó (bfa_…).
Công khai: /v1/links/{id} (liên kết luôn hoạt động), /v1/sso/discover, và API xác minh (/v1/public/*, /.well-known/bona-fide/keys.json).

Đăng nhập vào bảng điều khiển

Con người (không phải máy chủ) đăng nhập vào bảng điều khiển tại https://app.bonafidesign.com/sign-in. Mặc định là email và mật khẩu; các cách khác gồm mã sáu chữ số gửi qua email (Email me a code instead), magic link, passkey, Google hoặc Microsoft, và SSO của công ty bạn.

Tạo tài khoản bằng mật khẩu sẽ gửi một email: một mã xác nhận địa chỉ đó là của bạn. Trước khi xác nhận, mật khẩu chưa thể dùng để đăng nhập. Đăng ký bằng một địa chỉ đã có tài khoản sẽ không thay đổi gì và phản hồi giống hệt một lượt đăng ký mới; chủ sở hữu địa chỉ sẽ nhận được email hướng dẫn cách đăng nhập.
Mật khẩu dài từ 12 đến 128 ký tự và được lưu dưới dạng băm scrypt có salt. Mật khẩu mới xuất hiện trong một vụ rò rỉ dữ liệu đã biết sẽ bị từ chối: chỉ năm ký tự đầu tiên của giá trị băm SHA-1 được gửi đến Have I Been Pwned (k-anonymity), không bao giờ gửi mật khẩu. Nếu dịch vụ đó không phản hồi trong vòng hai giây, mật khẩu được chấp nhận mà không qua bước kiểm tra này.
Quên mật khẩu? Email đặt lại chứa liên kết đến một trang nơi bạn chọn mật khẩu mới. Liên kết chỉ dùng được một lần và hết hạn sau một giờ, và việc sử dụng nó sẽ đăng xuất bạn trên mọi thiết bị.
Chưa có mật khẩu? Tài khoản được tạo bằng mã, liên kết, passkey hoặc Google / Microsoft vẫn tiếp tục đăng nhập theo cách đó, và có thể thêm mật khẩu tại Settings › Account. Đặt mật khẩu lần đầu yêu cầu đã đăng nhập trong 15 phút gần nhất (trang sẽ gửi email cho bạn một mã để xác nhận đó là bạn); đổi mật khẩu yêu cầu mật khẩu hiện tại. Cả hai đều đăng xuất các phiên khác của bạn.
Lỗi không bao giờ tiết lộ tài khoản: mật khẩu sai, địa chỉ không tồn tại và tài khoản không có mật khẩu đều nhận cùng một phản hồi, và yêu cầu đặt lại luôn báo rằng email đang được gửi đi.
Giới hạn tần suất: các yêu cầu đăng nhập bằng mật khẩu, đăng ký và đặt lại bị giới hạn theo địa chỉ IP và theo địa chỉ email; khi vượt giới hạn, phản hồi là 429 cho đến khi hết khoảng thời gian giới hạn.
SSO của công ty: khi tổ chức của bạn bắt buộc SSO, các thành viên thuộc tên miền email của tổ chức chỉ đăng nhập qua nhà cung cấp danh tính. Mật khẩu, mã và magic link đều bị từ chối với họ; chủ sở hữu vẫn giữ mã qua email làm cách đăng nhập khẩn cấp.

Id của yêu cầu

Mọi phản hồi đều có header x-request-id, và mọi nội dung lỗi đều có requestId. Bạn có thể gửi x-request-id của riêng mình (từ 8 đến 128 ký tự thuộc A-Z a-z 0-9 . _ -) để đối chiếu nhật ký; nếu không, API sẽ tự tạo một id. Hãy cung cấp id này khi liên hệ bộ phận hỗ trợ.