认证与授权
本文说明当前代码实现的接入规则，不代表各环境已发布或可用。实际接入前请确认目标环境的发布状态与配置；文档站可访问不等于 API / MCP 服务已就绪。
两类凭证
| OAuth 用户令牌 | AppKey | |
|---|---|---|
| 面向 | AI 客户端（MCP） | 集成商服务器对接 |
| 获取方式 | 当前租户超级管理员浏览器授权（零密钥操作） | 当前租户超级管理员在控制台创建 |
| 绑定身份 | 授权操作的超级管理员本人及其租户 | 创建人本人及其租户 |
| 传递方式 | Authorization: Bearer <token>（客户端自动） | X-App-Key + X-App-Secret 请求头 |
| 有效期 | access token 默认 7200 秒（2 小时，可配置）；客户端使用刷新令牌续期（刷新令牌 90 天） | 无固定到期时间，但受吊销、当前身份和租户状态约束；MCP 收费通过结果另有固定 2 小时缓存 |
两类凭证都绑定员工身份：一切调用都以某个员工的身份执行， 平台不存在游离于权限体系之外的"系统级"凭证。
MCP 身份与付费准入
MCP 是付费增值服务，仅限当前租户超级管理员（SUPERADMIN）；普通管理员、员工或仅角色名称含“管理员”均不满足条件。
租户必须启用，主套餐为 ACTIVE 且处于有效起止时间内，同租户 MCP 订阅权益有效。若主套餐未明确包含 MCP，先在主站 服务订阅 → 增值市场（/service-subscription?tab=market）购买，再授权。
权益来源有两种：有效主套餐明确包含 MCP 资源，或同一订阅下有效的 MCP 加购。当前 PM 实现保留 PLAN 来源的套餐资源策略：UNLIMITED，或 LIMITED 且权益值大于 0，可通过准入；加购则须校验有效状态、购买数量和起止时间。历史 extraQuota、手工调增额度或任意主套餐本身不是有效 MCP 权益证明。不能把此规则写成“所有租户都必须额外购买”，也不能理解为无需 MCP 订阅权益。
服务端按当前租户的真实身份核验，不按角色名称判断：业务租户登录态须属于该租户，且 roleScope=0 或 maxRoleScope=0。平台管理端、供应商端登录态不能用于签发租户凭证；每次受保护请求还会重新核验绑定用户在该租户中的有效身份和超级管理员资格。
收费校验与身份校验的频率不同：凭证、当前超级管理员资格和租户状态仍在每次 MCP 请求时校验；正常 MCP 请求命中有效收费缓存时，不远程查询 PM。
| 阶段 / 凭证 | 收费校验与缓存 |
|---|---|
| OAuth 授权页面预检、首次授权码换 token、每次 refresh | 每次都远程核验 PM 收费权益，不能用调用期缓存替代；首次换 token 与 refresh 保留既有收费校验 |
| 已签发的 access token | 收费通过结果缓存到该 token 自身到期；命中不续期，期限不滑动 |
| 旧 token 或收费缓存丢失 | 首次使用补验一次；成功后只缓存至该 token 原到期时间，不重新给满 2 小时 |
| AppKey 请求 MCP | 没有 refresh，收费通过结果固定缓存 2 小时；命中不续期，到期后下次调用补验 |
access token 默认有效期为 7200 秒，可配置；refresh 由客户端发起，不是服务端每两小时定时刷新。 收费到期 / 取消导致不再具备有效 MCP 权益后，已签发 token 最长延迟一个 access token 有效期才拒绝（默认最多 2 小时，实际可能因提前刷新或补验而更早拒绝）；AppKey 最长延迟固定 2 小时。 此延迟不改变权益截止日期，也不适用于撤销授权、管理员降权、员工或租户禁用。
首次换 token / refresh 已完成实时收费核验并成功签发后，若仅辅助 paid marker 写入 Redis 失败，服务端记录日志，仍返回已签发 token，不因此返回 503。授权码此时已消费或 refresh 已轮换，不应误导客户端重试旧凭证。marker 缺失时，后续首次 MCP 请求补验；成功后仍只缓存至原到期时间。
MCP 请求侧 Redis 无法安全读写收费缓存，或需要远程核验时 PM 不可用，返回 503，不免费放行。上述签发后辅助写入的处理不豁免请求侧校验故障。
已有可读取的有效收费缓存不需 PM，也不受 PM 故障影响；但凭证与身份链仍须正常通过，身份服务故障仍可能返回 503。
本页不将 AppKey 作为 MCP 客户端接入方式；上述 AppKey 缓存规则只是说明它不能绕过收费准入。
这项 MCP 权益校验不扩展到 REST /v1/api/invoke，REST 仍执行原有凭证与权限校验。
单独加购 MCP 按年复购增加时长，不增加调用次数。有效截止为 min(paidEnd, mainEnd)，主套餐续订只能解锁尚未到期的已购 MCP 时长，不会暂停计时或补回天数；
完整规则见MCP 是什么。此处不额外要求付费主套餐或排除试用，可购资格以实际策略为准。
权限判定：scope ∩ 员工本人权限
授权范围（scope）按 {业务域}:{read|write} 词汇管理，如 sales:read、finance:write。
凭证实际能做的 = 凭证被授权的 scope ∩ 绑定员工本人的权限（功能权限 + 数据权限）
第一道闸 注册表白名单 @ 开放平台（接口未登记或停用即拒绝）
第二道闸 scope 校验 @ 开放平台（接口声明的 域:读写 必须被 scope 覆盖）
第三道闸 员工功能权限 @ 开放平台（按目标 URL 对照员工角色权限，与网关同源）
第四道闸 数据权限 @ 各业务微服务（按绑定员工真实身份执行，决定能看多少数据）
功能权限对应"员工在主站能不能用这个模块"，数据权限对应"能看到多少数据"—— 两者都以绑定员工本人为上限，与主站界面完全同口径。
两个推论：
- 超级管理员资格是接入前提；授权人被降权为普通员工后会在入口被拒绝，不会自动降级成普通员工凭证继续访问；
- 员工权限再大，凭证只授了
sales:read，也碰不了采购、改不了任何数据。
当前身份在每次受保护请求时重新核验；绑定员工丧失超级管理员资格、禁用 / 离职或租户禁用后，已有凭证也会被拒绝，不能等待刷新周期继续使用。 身份服务不可用时拒绝放行，但不应将服务故障当作授权人失去资格；收费链路按上文缓存与补验规则处理。具体 HTTP 401 / 403 / 503 含义见错误码。
AppKey 使用
当前租户超级管理员在控制台创建用于 REST 的 AppKey（选择用途名称与授权范围），Secret 明文仅创建时显示一次， 平台只存哈希、不可再查。调用开放接口时携带请求头：
X-App-Key: oak_xxx
X-App-Secret: oas_xxx
长期集成可使用符合超级管理员资格的专用集成账号，但专用账号仍受身份、租户状态与权限校验约束，并不保证永久有效。
撤销与生效时机
- 用户可撤销自己给 AI 工具的授权；当前租户超级管理员可吊销本租户的 AppKey
- 撤销/吊销即时生效（校验缓存同步清除）
- 刷新令牌每次使用即轮换；同一有效授权链内重用已轮换令牌按泄露处理并吊销该链。重新授权已作废的历史令牌只被拒绝，不得误吊销新的授权
安全边界
- 开放平台不经主站网关，全部权限判定在平台内完成，接口未登记即拒绝
- 强制 PKCE（S256）、授权码一次性、令牌与 Secret 一律哈希存储、明文不落日志
- 匿名注册与令牌端点均有 IP 限流