外观
API 分区
目标：说清 ATKONBASE 对外暴露的几条 API 通路各自的边界、鉴权方式与适用对象，避免调错通路。
ATKONBASE 的 HTTP 接口分三类。集成方只对接前两类；第三类不对外。
| 通路 | 路径前缀 | 鉴权 | 谁用 | 是否对外 |
|---|---|---|---|---|
| V1 集成 API | /v1/** | client credentials token（可叠加委派头） | 集成方应用代理终端用户 | ✅ 对外 |
| public 匿名分享 API | /public/s/{tenantCode}/{token}/** | 无 token，靠分享链接本身 + 可选密码 ticket | 终端用户匿名访问分享链接 | ✅ 对外 |
| Console 管理 API | （Console 内部） | 管理端登录态 | 租户管理员在 Console 内操作 | ❌ 不对外 |
V1 集成 API（主通路）
集成的主战场：认证、上传 / 下载、元数据读写、ACL、版本、生命周期等业务能力都在这里。
- 鉴权走
Authorization: Bearer <token>，token 由/v1/auth/token用 client credentials 换取；按需叠加委派头（见集成拓扑）。 - 统一返回体
ResponseDTO<T>：code = 0成功、非 0 失败，HTTP status 统一 200，业务结果由body.code区分。错误码清单见错误码参考。 - 完整端点契约 + Try-it 演练见 V1 集成 API 接口参考。
public 匿名分享 API（分享通路）
服务于「终端用户拿到一条分享链接，匿名访问」的场景：拉元信息、（需要时）验密码换一次性 ticket、下载。
- 无 token。鉴权通过
verifyPassword颁发的 IP-bound ticket 表达。 - 只覆盖匿名分享相关端点，与 V1 业务 API 在类型与路径上彻底隔离。
- 在 SDK 里走独立的 public client（见 SDK 总览）；端点契约见接口参考的「公开分享 API」分区。
⚠️ ticket 是 IP 绑定的：
verifyPassword的调用方与最终下载方必须是同一公网出口 IP。服务端代理场景下不要把 ticket 透传给前端浏览器，应由集成方服务端自己流式转发下载。细节见 SDK 文档。
Console 管理 API（不对外）
Console 是仅租户管理视角的管理端（开通租户、申请 API 凭据、管理角色 / 菜单等），不是业务视角，也不对集成方开放为可编程 API。管理端专用的错误码不会在 V1 / public 对外通路返回——对接时无需关心它们。