Device Authorization

CLI、电视和其他输入受限设备通过用户在独立浏览器确认，获得 OAuth 令牌。

启用与发起

在 Application 中启用 Device Code。分发型客户端通常选择 public；只有能够安全保存密钥的服务端才使用 confidential。Device-only 应用不需要 redirect URI。

从 Discovery 读取 device_authorization_endpoint，当前为 /api/auth/device/code。public 客户端提交 client_id、所需 scope，必要时提交获准的 resource；confidential 客户端同时按登记的 token endpoint 方式认证。

POST /api/auth/device/code
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&scope=openid%20profile%20email

响应包含 device_code、user_code、verification_uri、expires_in 和 interval。只向用户展示 verification URL 和 user code，保护 device code。

用户确认

用户访问 /device 后选择账号、核对设备上显示的 code，明确批准或拒绝。批准会创建和浏览器授权同样可见、可撤销的 OAuth authorization。不要自动替用户点击批准，也不要用一等会话 token 替代 OAuth token。

轮询令牌

向 Discovery 的 token_endpoint 发送：

grant_type=urn:ietf:params:oauth:grant-type:device_code
client_id=YOUR_CLIENT_ID
device_code=DEVICE_CODE

首次和后续轮询遵守返回的 interval。遇到 authorization_pending 继续等待；遇到 slow_down，将之后的轮询间隔增加五秒。遇到拒绝、过期或其他终止性的 OAuth 错误停止轮询。HTTP 429 时保留当前设备码，按照 Retry-After 等待；服务暂不可用时使用有上限的退避，不要立即生成新码或无限重试。详见错误码与请求诊断。

成功后按令牌校验验证结果。KAI 有意关闭 /api/auth/device/token，本流程使用 /api/auth/oauth2/token 发放 OAuth 令牌，不创建一等登录会话。

离线授权与退出

需要浏览器关闭或退出后继续访问时，在应用登记并请求 offline_access，由用户批准后获得 refresh token。之后用户在批准页面切换账号、退出 Auth 或来源会话过期，不会撤销这次已完成的离线授权；尚未批准的请求不能因此直接取得令牌。

Device Code 与 Authorization Code 的刷新、UserInfo 和 Introspection 使用相同的原始认证证据与当前安全策略。已撤销授权、过期刷新令牌、账号或组织限制仍会导致失败。保存并轮换 refresh token，不要每隔五分钟要求用户重新输入设备码，也不要依赖一个持续活跃的浏览器 sid。kai_offline_grant_id 是 Auth 的内部授权标识，不能代替 token。

第三方 CLI 清理本地令牌只退出该应用；要让服务端凭据失效，调用 Discovery 的撤销端点。KAI 自带 kai-auth logout 管理的是当前 profile 的开发者会话，不能把它当作第三方应用的 OAuth 撤销命令。更多边界见退出与授权撤销。

与额外身份验证的区别

Device 授权成功表示用户批准当前客户端登录，不表示完成了一次高风险操作的额外验证。当前 Device 请求不支持通过 acr_values 取得 kai_step_up 结果；刷新 Device 令牌或在浏览器做过其他验证，也不会升级原授权链。

应用或 CLI 需要额外验证时，另行发起额外身份验证的授权码与 PKCE 流程，并核对结果属于当前业务账号。不要调用 KAI 的私有浏览器会话接口来绕过这项边界。