KAI Auth 接入文档
从应用登记到令牌校验，用同一套 OAuth 2.0 / OpenID Connect 契约接入 KAI 账号。
适用版本
本文对应 KAI Auth 当前实现，认证组件为 Better Auth / OAuth Provider 1.7.1。页面随代码发布；如文档示例与目标环境的 Discovery 不一致，先核对环境和发布版本，不要自行放宽验证。
生产 issuer 为 https://auth.kai.com。协议端点位于 /api/auth 下；issuer 不包含该路径。浏览器、服务端和原生应用共用授权服务器，各应用登记并处理自己的回调地址。
开始接入
- 在开发者控制台选择组织和项目，创建 Application，参阅应用登记与回调。
- 按授权码与 PKCE实现登录，始终验证
state、nonce、签名、issuer 和 audience。 - 纯登录先使用
openid profile email，不发送resource。调用业务 API 时阅读资源与访问令牌。 - 使用OAuth 测试应用按实际授权流程检查连接。一次成功登录不等于所有授权、撤销和业务接口都已通过验收。
- 高风险操作需要用户重新证明身份时，接入额外身份验证。应用只取得验证结果，不取得具体高等级认证方式。
使用终端或 Agent 配置应用时，参阅Auth CLI。其中 oauth step-up 用于应用侧额外验证，管理 step-up 则用于控制台敏感操作，两者的凭据不能互换。
选择流程
| 应用 | 客户端类型 | 流程 |
|---|---|---|
| 有安全服务端的网站 | confidential | Authorization Code + S256 PKCE，服务端保管 secret |
| 浏览器 SPA、移动端 | public | Authorization Code + S256 PKCE，无共享 secret |
| CLI、电视等输入受限设备 | 通常 public | Device Authorization，应用须启用 Device Code |
KAI 控制台提供的应用以用户授权为核心，不能仅根据 Discovery 中列出的通用能力推断某个应用已启用相应 grant。
机器可读入口
- OIDC Discovery与OAuth Discovery：运行环境的协议元数据。
- OpenAPI：KAI 自有管理 API 的生成契约；OAuth/OIDC 端点通过 Discovery 发现。
- 文档索引与完整文档：供 AI 工具读取。
- 每篇文章支持
Accept: text/markdown，也可直接打开路径后的/index.md，例如/docs/authorization-code/index.md。
文档正文在服务器生成，无需 JavaScript。HTML 与 Markdown 来自同一份内容；搜索和复制按钮只是阅读辅助。