跳转到内容
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。