个人访问令牌
个人访问令牌(PAT) 是您自己创建并粘贴的凭据。它适用于 Waafir REST API 和脚本,以及无法登录的 AI 助手:大多数助手只需粘贴 Waafir URL 并登录即可连接,完全不需要令牌。在 Waafir 的 MCP 服务器上,每个请求要么携带通过登录建立的连接,要么携带有效的 PAT。不存在匿名访问,并且此接口不接受普通的已登录浏览器会话(以会话认证的请求会被拒绝)。PAT 以您的身份在您的组织内执行操作,并受您签发时所选择的权限范围和数据室的限制。
在哪里签发令牌
打开 附加功能 → 配置 → API令牌。该页面包含三个部分:签发新令牌的表单、您现有令牌的列表(带撤销操作),以及一段用于通过令牌连接助手的、可直接使用的配置代码片段。
要签发令牌,请填写表单:
- 名称 — 便于您日后识别该令牌的可读标签(例如“Claude Desktop – 笔记本电脑”)。必填。
- 范围 — 该令牌被允许执行的操作。见下文。
- 数据室范围 — 保持勾选 所有数据室,让令牌可以访问您能访问的每个数据室;或者取消勾选并选择特定数据室,将令牌限定于这些数据室。
- 过期时间 — 令牌在此日期之后停止工作。填写与否是可选的,但实际效果上并非可选:留空时,令牌会以 90 天 的有效期签发。请参阅过期时间。
权限范围
令牌带有三种权限范围之一,按权限从低到高排列:
| 权限范围 | 允许 | 典型用途 |
|---|---|---|
read | 列出和读取:数据室、文件夹、文件、文件元数据、搜索、下载 URL 以及查看权限;读取文档的提取文本;读取投资者问答线程;检查脱敏、翻译或电子签名作业的状态。 | 回答有关数据室问题的只读助手。 |
write | read 允许的一切,再加上变更操作:创建、重命名、移动、删除和恢复文件夹;上传、重命名、移动、删除和恢复文件,包括上传文件的新版本以及回滚版本;启动文档脱敏或翻译;以及创建、发送、拒绝和作废电子签名信封。发送信封(或向已发送的信封添加签署人)还需要 发送给组织外的人员,并且您的助手会在发送前请您确认。签署(esign_sign)还需要 签署文件,同样会先请您确认。 | 整理或维护数据室的助手。 |
admin | write 允许的一切,再加上四个授予权限的工具:授予或撤销用户对文件和数据室的访问权限。请注意,三个读取权限的工具只需要 read。 | 管理谁可以看到什么内容的助手。 |
权限范围是累积的:较高的权限范围包含其下所有权限。每个服务器的工具参考都写明了每个工具所需的最低权限范围。
谁可以签发各权限范围
令牌所携带的权限永远不能超过签发它的人:
read和write可以由您组织中的任何活跃成员签发。admin只能由组织的所有者或管理员签发。如果您不是所有者或管理员,范围选择器中不会出现admin选项。- 投资者(以及其他非交易团队角色)完全不能签发令牌。
除签发之外,admin 权限工具在调用时还会施加第二重上限:令牌的所有者本人必须是该组织中的管理员或经理,权限授予才能成功。令牌的权限范围是令牌的上限;所有者的角色是人的上限,管理员操作必须同时满足两者,这与产品界面所应用的规则完全相同。通过 MCP 不存在比通过产品更宽松的路径。
允许令牌签署文档
签署需要开启了 签署文件 的令牌。您在 附加功能 → 配置 上为 write 或 admin 令牌创建令牌时选择此项,因此只有您信任的助手才能代您签署。如果您开启了双因素认证,创建令牌时本身就会要求输入双因素验证码,因此这项检查覆盖了该令牌所做的每一次签名。令牌列表会在每个此类令牌上显示 可以签署。
您的助手会先向您展示文档、签署人和字段,只有在您确认后才会签署。未开启 签署文件 的令牌在工具列表中看不到 esign_sign,如果调用它也会被拒绝。在此选项推出之前创建的令牌无法签署:请创建一个开启了 签署文件 的新令牌。
允许令牌读取文档内容
完整读取文档,或向 AI 询问有关文档的问题,需要开启了 读取文档内容 的令牌。您在 附加功能 → 配置 上创建令牌时选择此项,任何权限范围均可。令牌列表会在每个此类令牌上显示 文档内容。它涵盖:
get_file_text,文档的完整提取文本;get_file_download_url,下载文件的链接;esign_download_signed,已签署的电子签名 PDF;translate_file_status为已完成的翻译返回的下载链接;GET /api/v1/files/{fileId}/content,通过 REST API 获取的文档字节;POST /api/viewer/token、POST /api/viewer/artifact-access和POST /api/viewer/artifact-access/unlock,它们生成产品内文档查看器流式加载文档所依据的查看器令牌或 cookie;- 由您编写问题或输入的 AI 工具,因为回答可能会复述文档的内容:
dataroom_ask、dataroom_draft_answer、dataroom_compare_files和dataroom_generate_update; POST /api/v1/chat,通过 REST API 获取的同一 AI 回答;GET /api/v1/facts返回的每条事实的quote。
没有此项的令牌会被拒绝使用这些工具(GRANT_REQUIRED)和这些 REST 路由(PAT_GRANT_REQUIRED),并且 translate_file_status 会返回状态以及 download_withheld_reason: content_grant_required,而不是链接。GET /api/v1/facts 和 dataroom_list_facts 返回的每条事实都不含 quote,value 被截断为 20 个单词,并设置 value_truncated。该令牌仍然可以列出和搜索,并可以通过 get_file_metadata 或 dataroom_summarise_file 读取文档摘要。在此选项推出之前创建的令牌无法读取文档内容:请创建一个开启了 读取文档内容 的新令牌。服务令牌不受影响。
每个令牌每分钟最多可以获取 10 个下载链接。超过此限制后,get_file_download_url 会被拒绝(RATE_LIMITED),translate_file_status 会返回状态以及 download_withheld_reason: rate_limited;请在一分钟后再次请求。
允许令牌向组织外的人员发送
创建分享链接、添加快照查看者、邀请团队成员或投资者,以及延长或恢复投资者的访问权限(dataroom_extend_investor_access、dataroom_reinstate_investor_access)都会将访问权限交给您组织之外的人,因此它们需要开启了 发送给组织外的人员 的令牌(与发送投资者更新、问答回复和电子签名请求的授权相同)。您在 附加功能 → 配置 上创建 write 或 admin 令牌时选择此项。令牌列表会在每个此类令牌上显示 可以外部发送。
您的助手会先向您展示新链接允许谁访问、NDA 规则和过期时间,只有在您确认后才会创建该链接。撤销链接或查看者不需要任何授权。
该授权还涵盖向交易团队(所有者、管理员和成员)之外的人授予数据室或文档的访问权限或更多访问权限。“之外”是指任何不是该数据室所属组织的活跃交易团队成员的人:投资者、访客、有待处理邀请的人,以及其他组织的成员。没有此授权时,令牌在以下情况下会被拒绝(在 MCP 上为 GRANT_REQUIRED):
- 向此类人员授予读取或下载权限:
set_file_permissions、dataroom_set_folder_permissions、dataroom_bulk_set_file_permissions; - 移除此类人员的拒绝规则,从而恢复其访问权限:
revoke_file_permission、dataroom_revoke_folder_permission、dataroom_bulk_revoke_file_permissions; - 为此类人员提供任何级别的数据室访问权限:
invite_user_to_dataroom; - 更改当前角色不属于交易团队的成员的角色,这会提升其权限:
dataroom_team_change_member_role; - 扩大访问权限的投资者变更:
dataroom_set_investor_permissions从查看者改为下载者、关闭 NDA,或开启监控或更新。
拒绝规则、终止授权以及向您的交易团队授权都不需要此授权。将内容放到某人已有访问权限的位置(上传、移动、发布)不在此范围内。附加该公司已签署的公司 NDA 不需要此授权。
使用个人访问令牌发出的以下 REST 调用也适用同一授权:
POST /api/share-links(创建链接)和POST /api/snapshots/{id}/viewers在没有此授权时会以403 PAT_GRANT_REQUIRED被拒绝;POST /api/investors/invite(它会创建个人链接并通过电子邮件发送)也会以同样方式被拒绝;PATCH /api/investors/{id}/extend和PATCH /api/investors/{id}/access(恢复投资者或批准访问请求)也会以同样方式被拒绝;撤销投资者(DELETE /api/investors/{id}/access)不需要授权;POST /api/team、POST /api/v1/team和POST /api/team/resend(团队邀请会通过电子邮件发送加入链接)也会以同样方式被拒绝;PATCH /api/share-links/{id}对链接访问设置的任何编辑都会被拒绝(开启链接、其模式、域名、过期时间或 NDA,无论该编辑是放宽还是收紧设置);关闭链接始终是允许的;GET /api/share-links返回的每个链接都不含url和token,并标记为urlWithheld: true,同时附带说明原因的urlWithheldReason;POST /api/v1/grants向交易团队之外的人授予读取或下载权限时会被拒绝;当授权是该人员的拒绝规则时,DELETE /api/v1/grants/{id}会被拒绝;当成员的当前角色不属于交易团队时,PATCH /api/v1/team/{id}会被拒绝。
这些检查按照服务器路由的方式读取路径,因此末尾的斜杠或百分号编码的字符无法绕过它们。无法解码的路径,或者包含 ./.. 段或在段内包含编码后的 / 的路径,无法与授权所涵盖的任何调用匹配。因此,缺少任何按请求授权(本授权、读取文档内容 或 读取参与度分析)的个人访问令牌,其所有此类路径都会以 403 PAT_PATH_MALFORMED 被拒绝,无论是什么调用。
在此授权推出之前创建的令牌不具备该授权,因此在您创建开启了该选项的新 write 或 admin 令牌之前,它们无法执行这些调用。read 令牌不能拥有此授权。
允许令牌读取参与度分析
读取参与度分析 允许令牌读取谁在何时查看了哪些文档以及查看了多长时间:即参与度工具,以及投资者名册上的参与度信息。请只为应当看到这些信息的助手开启此项。任何权限范围都可以拥有它。
同一授权也适用于 REST 活动读取:GET /api/v1/activity(组织的活动和审计信息流)、/api/v1/activity/rollups、/api/v1/activity/engagement、/api/v1/activity/engagement/documents 和 /api/v1/activity/engagement/document/pages。没有此授权时,个人访问令牌会以 403 PAT_GRANT_REQUIRED 被拒绝。服务令牌和已登录会话不受影响。
在这些选项推出之前创建的令牌两者都不具备:请创建一个开启了该选项的新令牌。
将令牌限定于特定数据室
默认情况下,令牌可以访问其所有者能够访问的每个数据室。取消勾选 所有数据室 并选择特定数据室,即可将令牌限定于该允许列表:任何引用列表之外数据室的工具调用都会被拒绝,并且受限令牌甚至看不到它无法打开的数据室的名称。使用此功能可以让 AI 客户端访问某一笔交易,而不暴露您投资组合中的其他交易。
过期时间
每个令牌都会过期。不存在永久有效的 PAT:永不过期的令牌本身就是此行为旨在消除的安全隐患,因为被遗忘的凭据会永远有效。设置过期日期后,令牌会在该日期之后停止工作:使用已过期令牌的请求会像已撤销令牌一样被拒绝,返回 HTTP 401。
- 将该字段留空,您将获得 90 天,从令牌签发的那一刻起计算。留空表示使用默认值,而不是永不过期。
- 设置日期后,会严格按照该日期执行,上限为签发后 365 天。
- 请求超过 365 天会被拒绝,而不会被悄悄缩短:签发过程绝不会在不告知您的情况下返回一个有效期比您要求的更短的令牌。过去的日期也会以同样方式被拒绝。
因此,如果某个集成需要持续运行,请有意识地设置过期时间,并在日历中设置提醒,在令牌失效前更换它:留空的字段会在您设置该集成大约三个月后悄无声息地使其停止工作。现有令牌没有续期或轮换操作,过期前也没有任何警告:更换令牌意味着签发新令牌、更新客户端配置并撤销旧令牌。反过来说,对于为一次性任务签发的令牌,较短的有效期正好合适。
附加功能 → 配置 上的令牌列表会显示每个令牌的过期时间,方便您查看哪些令牌即将失效。
一次性显示
签发令牌时,原始值(以 waafir_pat_ 开头)会在创建后立即显示,且仅显示一次。Waafir 从不存储原始令牌,只存储其单向哈希值,因此它无法被找回或再次显示。
- 立即复制,并将其直接粘贴到客户端配置中。显示面板上有复制按钮。
- 如果丢失,您将无法找回:请撤销该令牌并签发一个新令牌。
- 请像对待密码一样对待它:任何持有它的人都能获得其权限范围。
显示之后,令牌列表只会显示一个简短的、非机密的前缀(例如 waafir_pat_ab12…),以便您区分各个令牌,同时无法找回密钥。
撤销令牌
在 附加功能 → 配置 上的令牌列表中,使用任一令牌旁边的 撤销 操作。撤销立即生效:下一个使用该令牌的请求会被拒绝。一旦设备丢失、承包商离开,或者您只是不再需要该访问权限,请立即撤销令牌。已撤销的令牌仍会显示在列表中(标记为已撤销),以保留曾经存在过哪些令牌的记录;它们永远无法被重新激活。
令牌自行终止的情况
令牌通过您在组织中的成员身份执行操作,因此当该成员身份终止时,令牌也随之终止。在以下情况下,您无需自行撤销:
- 您离开组织,或管理员将您移除。 您在该组织中持有的每个令牌都会在那一刻被撤销。您在其他组织中持有的令牌继续有效。
- Waafir 管理员删除了您的账户。 您在每个组织中的令牌都会被撤销。
- Waafir 管理员删除了该组织。 其中的每个令牌都会被撤销,包括其服务令牌。
这些撤销是永久性的。被重新邀请加入,或者您的账户或组织被恢复,都不会让令牌恢复:请签发一个新令牌。
服务令牌属于组织,而不属于创建它的管理员,因此当该管理员离开时它仍会继续工作。只有撤销它或删除组织才会让它提前终止。
审计日志中的令牌历史
每次签发或撤销令牌都会在组织的审计日志中写入一行:操作者、令牌的名称、权限范围、权限和过期时间、它被限定于多少个数据室,以及它被撤销的原因(由其所有者撤销、因成员身份终止,或因账户或组织被删除)。令牌本身、其哈希值和前缀永远不会被记录。这些行会出现在完整的活动记录中,而不会出现在仪表板摘要中。
如果 Waafir 无法在审计日志中记录新令牌,则不会签发该令牌,您会看到“The token wasn't created because we couldn't record it. Try again.”(由于我们无法记录该令牌,令牌未被创建。请重试。)
下一步:使用您刚签发的令牌设置您的客户端。