接口认证与密钥作用域

开放接口认证

开放接口使用 Authorization: Bearer <密钥>。本手册将调用开放接口的密钥统称为开放密钥，按作用域分为超级密钥（平台作用域）与资源密钥（应用、智能体、知识库作用域）。密钥所属租户、作用域、资源主键和有效期共同决定可调用范围；管理后台的登录令牌用于另一条认证链路。

一、作用域

作用域	调用范围
平台	平台开放端点及其覆盖的租户资源
应用	指定应用的开放端点
智能体	指定外部智能体的开放端点
知识库	指定知识库的检索与问答

资源级密钥还会核对实际资源。将 URL 中的主键改成其他应用，不会扩展原密钥范围。知识检索同时检查请求体中的目标知识库和开放状态。

二、签发与保存

平台作用域的密钥即超级密钥，在 运营治理 → 超级密钥 中管理；资源密钥在对应资源的工作区中管理。签发时填写名称与到期时间，明文只在签发时返回一次，需立即保存。

密钥明文

系统保存密钥摘要和前缀，签发后不能从列表恢复完整明文。业务程序从运行环境读取密钥，页面、日志与公开示例只展示占位值。

三、验证认证链路

先调用模型列表或对应资源的模型列表，确认服务路径与作用域，再发起生成请求：

curl "$AI_API_BASE/v1/models" \
  -H "Authorization: Bearer $AI_API_KEY"

平台端点需要超级密钥；应用的资源密钥调用 /app/{id}/v1/models。

未携带有效认证时返回 HTTP 401，响应体如下：

{"code":401,"success":false,"data":null,"msg":"请求未授权"}

四、生效与记录

ApiAuthAspect 执行开放认证，TokenAuthenticator 核对密钥及资源，执行租户取自密钥。调用记录标注 API 渠道及密钥归属，用于在用量和运行记录中追踪请求。

认证失败时依次检查请求头、有效期、作用域、资源主键及资源开放状态。操作见 超级密钥。