跳至內容
bona fidedocs

驗證身分

API 使用組織 API 金鑰來驗證伺服器的身分。金鑰屬於某個組織（而不是某個人），帶有一組權限，而且只在一種模式下有效：測試或正式。

傳送金鑰

標題為「傳送金鑰」的章節

使用下列任一標頭：

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

金鑰的格式為 bf_live_… 或 bf_test_…。缺少金鑰時會傳回 401（unauthorized）；金鑰格式錯誤、已撤銷或已到期時同樣會傳回 401。請將金鑰保存在伺服器上：切勿將其發布到瀏覽器或行動應用程式中。若要在瀏覽器中簽署，請改為核發簽署工作階段。

測試金鑰與正式金鑰

標題為「測試金鑰與正式金鑰」的章節
測試（bf_test_…） 正式（bf_live_…）
文件 轉譯時加上 TEST 浮水印 無浮水印
電子郵件 只寄給您組織的成員 寄給每一位收件者
計費 免費且無限量，絕不計入用量 已完成的信封會計入您的方案用量
資料 以該金鑰建立的信封、連結和 Webhook 端點皆屬於測試模式 正式模式

模式由金鑰決定，而不是由要求決定：POST /v1/envelopes 上的 ?test_mode=true 只適用於主控台工作階段。清單（GET /v1/envelopes、GET /v1/signing-links）只會傳回與金鑰相同模式的內容，信封的事件也只會傳送到相同模式的 Webhook 端點。每個信封和 Webhook 承載都會註明其所屬模式（testMode）。

建立和撤銷金鑰

標題為「建立和撤銷金鑰」的章節

金鑰在主控台的 設定 › API 金鑰 中管理，須由具備 apikey:manage 權限的成員（擁有者和管理員）操作。金鑰的密碼值只會在建立時顯示一次。您可以為金鑰設定名稱、模式、有效期限（1 到 365 天，或永不到期）以及權限範圍。

權限範圍

標題為「權限範圍」的章節

金鑰的權限範圍，就是它可以使用的組織權限。根據預設，新金鑰會取得建立者的權限，但不含管理類權限（org:manage、member:manage、sso:manage、apikey:manage、billing:manage），而且任何人都無法授予金鑰自己沒有的權限。超出金鑰權限範圍的呼叫會傳回 403，並指出缺少的權限：

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}
權限 允許金鑰
template:read 列出和讀取範本、版本及其 PDF
template:write 建立範本、上傳檔案、儲存草稿、刪除未使用的範本
template:publish 將草稿發布為新版本
envelope:read 列出和讀取信封、文件及稽核軌跡；列出簽署連結
envelope:send 建立信封、簽署工作階段和簽署連結；重新寄送連結
envelope:void 作廢進行中的信封
org:manage 管理 Webhook 端點並重新傳遞事件；讀取組織設定
billing:manage 讀取用量（GET /v1/usage）和帳單金額

管理 Webhook 端點需要 org:manage，而金鑰預設沒有這項權限：請在主控台中註冊端點，或明確建立一個具備該權限範圍的金鑰。

各端點接受的憑證

標題為「各端點接受的憑證」的章節

API 參考中的每項作業都列出了其安全性配置。簡單來說：

  • API 金鑰或主控台工作階段：範本、信封、簽署工作階段、簽署連結、Webhook 端點、組織設定、帳單概覽和用量。
  • 僅限主控台工作階段：API 金鑰、SCIM 權杖、SSO 連線設定、組織標誌上傳、帳單結帳與客戶入口網站、顯示 Webhook 密鑰。
  • 簽署人權杖：/v1/signing/*，由託管頁面和 <bf-signing> 搭配工作階段權杖（bfs_…）或由其交換而得的存取權杖（bfa_…）使用。
  • 公開：/v1/links/{id}（常設連結）、/v1/sso/discover 以及驗證 API（/v1/public/*、/.well-known/bona-fide/keys.json）。

登入主控台

標題為「登入主控台」的章節

使用者（而非伺服器）在 https://app.bonafidesign.com/sign-in 登入主控台。預設方式是電子郵件和密碼；其他方式包括以電子郵件寄送的 6 位數驗證碼（改用電子郵件寄送驗證碼）、魔術連結、密碼金鑰、Google 或 Microsoft，以及貴公司的 SSO。

  • 以密碼建立帳戶時會寄出一封電子郵件：其中的驗證碼用來確認該地址屬於您。確認之前，密碼無法用於登入。如果使用已有帳戶的地址註冊，不會做任何變更，傳回的回應也與全新註冊完全相同；該地址的擁有者會收到一封電子郵件，說明應如何登入。
  • 密碼長度為 12 到 128 個字元，以加鹽的 scrypt 雜湊形式儲存。出現在已知資料外洩事件中的新密碼會遭到拒絕：只有其 SHA-1 雜湊的前五個字元會傳送到 Have I Been Pwned（k-匿名性），密碼本身絕不會傳送。如果該服務在兩秒內沒有回應，就會略過這項檢查並接受該密碼。
  • 忘記密碼？ 重設郵件中的連結會開啟一個頁面，讓您設定新密碼。該連結只能使用一次，一小時後到期；使用後，您會在所有裝置上登出。
  • 還沒有密碼？ 以驗證碼、連結、密碼金鑰或 Google / Microsoft 建立的帳戶可以繼續用原本的方式登入，也可以在 設定 › 帳戶 中新增密碼。第一次設定密碼時，必須在過去 15 分鐘內登入過（頁面會以電子郵件寄送驗證碼給您，確認是您本人）；變更密碼則需要輸入目前的密碼。這兩項操作都會讓您的其他工作階段登出。
  • 錯誤訊息絕不透露帳戶是否存在：密碼錯誤、地址不存在以及帳戶沒有密碼，這三種情況的回應完全相同；重設要求也一律回覆郵件已寄出。
  • 速率限制：密碼登入、註冊和重設要求會依 IP 位址和電子郵件地址分別限制；超出限制後，在時間範圍結束前都會傳回 429。
  • 公司 SSO：當您的組織強制使用 SSO 時，使用其電子郵件網域的成員只能透過身分識別提供者登入。這些成員無法使用密碼、驗證碼和魔術連結登入；擁有者保留電子郵件驗證碼作為緊急登入方式。

要求 ID

標題為「要求 ID」的章節

每個回應都帶有 x-request-id 標頭，每個錯誤回應本文都帶有 requestId。您可以傳送自己的 x-request-id（8 到 128 個字元，字元範圍為 A-Z a-z 0-9 . _ -）來對應記錄；否則 API 會自動產生一個。聯絡支援團隊時，請提供該 ID。