外观
集成拓扑
目标：说清集成方、终端用户、ATKONBASE 三者的调用关系，以及 TRUSTED_DELEGATED（受信委派）这一核心集成模式——它决定了你的请求里要带哪些身份信息。
三方角色
终端用户（企业员工 / 客户 / 供应商）
│ 在集成方的业务页面上传 / 查看 / 分享文档
▼
集成方应用（业务 UI / 表单 / 流程 / 自有用户体系）
│ 调 ATKONBASE V1 API（代理终端用户）
▼
ATKONBASE（多租户 / 容器 / 文档 / 版本 / ACL / 元数据 / 生命周期）关键点：
- 终端用户经集成方应用访问。他们看到的是集成方的品牌与界面，由集成方应用在底层代为调用 ATKONBASE 的内容能力。
- 集成方应用是唯一的 API 调用方。它持有 API Client 凭据（
clientId/clientSecret），代表终端用户向 ATKONBASE 发请求。 - 集成方自有用户体系。登录、邀请、密码重置等都在集成方侧；ATKONBASE 通过受信委派承接集成方转述的用户身份（见下文 TRUSTED_DELEGATED）。
TRUSTED_DELEGATED：受信委派模式
集成方不仅「以应用身份」调用，还经常需要「以某个终端用户的身份」调用——例如让 ACL 检查走该用户、让操作归属到该用户。ATKONBASE 称这种「应用代理终端用户」的关系为 TRUSTED_DELEGATED。
身份信息由请求头组合表达，分三种形态：
| 形态 | 含义 | 请求头 |
|---|---|---|
| APP_ONLY | 纯应用身份，无委派用户 | Authorization: Bearer <client token> |
| 强通道 | 应用代表一个已签发会话的用户 | 在上基础上加 X-Atk-User-Token: <user token> |
| 弱通道 | 应用主张代表一个外部身份 | 在上基础上加 X-Atk-Act-As-Source + X-Atk-Act-As-Source-Id |
⚠️ 强通道的
userToken与弱通道的actAs互斥，一次请求只能用其一。弱通道需由平台为该 Client 启用『代理外部身份』能力（actAsAllowed）。两通道的跨租户 / 同租户判定规则属于认证模式篇主题，入门只需知道「带哪个头」。
「为什么是 TRUSTED」：集成方应用是受信任的一方——它已经在自己侧完成了终端用户的认证，ATKONBASE 信任它转述的用户身份，而不要求终端用户再向 ATKONBASE 登录一次。
凭据与租户
clientId/clientSecret在管理端的「API 客户端」面板申请，集成方妥善保管，不可入仓。- 调
/v1/auth/token用 client credentials 换accessToken；tenantId由clientId在服务端解码得到，无需集成方回传。 - 一个 Client 归属一个租户；多租户场景下集成方为每个租户持有对应凭据。