组织、SSO 与 SCIM

Bona Fide 中的一切都属于某个组织（即工作区）：模板、信封、签署链接、Webhook 端点、API 密钥以及方案。每次注册都会获得一个个人组织，一个人也可以同时是多个组织的成员。API 密钥代表拥有它的那一个组织执行操作。

控制台会话作用于成员当前所在的组织；使用会话 Cookie 调用 API 的集成，可以通过 x-organization-id 请求头切换到该用户所属的其他组织。

角色与权限

每位成员有一个角色。每个角色对应一组固定的权限，每个端点都会检查某项权限：

角色	权限
`owner`	全部权限
`admin`	除 `billing:manage` 之外的全部权限
`sender`	`envelope:read`、`envelope:send`、`envelope:void`、`template:read`
`template_manager`	`template:read`、`template:write`、`template:publish`、`envelope:read`
`auditor`	`envelope:read`、`template:read`、`audit:read`
`billing`	`billing:manage`

完整的权限列表为 envelope:read、envelope:send、envelope:void、template:read、template:write、template:publish、org:manage、member:manage、sso:manage、apikey:manage、billing:manage 和 audit:read。API 密钥以权限范围的形式持有其中的一部分。

成员、邀请、团队和组织品牌在控制台中管理。组织徽标通过控制台会话调用 POST /v1/organization/logo 上传（PNG、JPEG、SVG 或 WebP，最大 512 KB）。

单点登录

所有者和管理员可以在设置 › 安全 › SSO 中自行连接其身份提供方（IdP），支持 SAML 2.0 或 OIDC：

使用 IdP 的元数据注册连接（控制台可以替您获取 SAML 元数据 URL）。
通过 DNS TXT 记录验证您的电子邮件域（令牌以 bona-fide-verify 开头）。
选择设置：即时预配（首次通过 IdP 登录时创建成员）、新成员的默认角色，以及强制执行：电子邮件属于已验证域的成员必须通过 IdP 登录；所有者保留应急登录方式。
在强制执行之前，先在连接页面上运行一次测试登录。

同一页面还会显示连接健康状况（上次登录、过去 30 天的登录次数、证书到期时间），以及每项 SSO 和 SCIM 变更的审计记录（GET /v1/sso/audit）。

登录页面会调用 GET /v1/sso/discover?email=… 来判断某个地址是否使用公司 SSO；该接口是公开的，并受速率限制。强制执行 SSO 后，该域将无法使用密码、电子邮件验证码和魔法链接登录。

SCIM 目录同步

借助 SCIM 2.0，您的 IdP 会自动创建、更新和停用成员。在设置 › 安全 › SCIM 中创建一个持有者令牌（只显示一次），然后将 SCIM 基础 URL 和该令牌提供给您的 IdP。基础 URL 为 https://api.bonafidesign.com/api/auth/scim/v2。创建新令牌会替换之前的令牌；撤销令牌则会停止预配。