千问办公企业旗舰版开发者文档:认证接入。
接入流程
APP 用户接口统一使用用户 Access Token。客户后台持有应用 API Key,按已验证的当前用户身份取得 QID,申请该用户的 Access Token,再调用 APP 业务接口。
| 调用阶段 | 凭据 | 用途 |
|---|---|---|
| 申请用户凭据 | 应用 API Key | 调用管理 OpenAPI 颁发入口 |
| 调用 APP 业务接口 | 用户 Access Token | 代表对应用户访问获授权资源 |
app.v1.user-tokens.issue,并配置应用可代办的用户范围。目标用户必须已存在、正常且满足席位、网页访问资格及身份绑定要求。客户后台应从自身可信登录态映射 QID,不接受客户端任意指定他人的 QID。
只有已激活(**active**)且未停用的用户才能获取 AccessToken。 未激活(pending)用户即使已分配席位,申请时仍会返回 403 app_user_token_denied;需先完成激活,再申请 Token。激活后仍须满足上述席位、网页访问资格、身份绑定及应用权限要求。
无需首次登录的用户激活
客户后台可在管理 OpenAPI POST /api/openapi/v1/users 中传 activate: true,或对已有未激活用户调用 POST /api/openapi/v1/users/{userId}/activate,无需用户先登录 QwenWork。创建即激活只需原有 admin.v1.user-directory.manage 权限;独立激活接口需要 admin.v1.users.activate 权限。激活保持邮箱验证、密码和席位不变,不代替席位授权、Web 使用资格或 Token 签发权限。申请 Access Token 本身不会激活用户。
申请 Access Token
客户后台调用 POST /api/openapi/v1/app-user-tokens。请求体仅包含 qid;组织、应用和 Key 身份由服务端根据 API Key 确定。完整字段和状态定义见管理 OpenAPI 的“申请用户 Access Token”接口。
200 和 Cache-Control: no-store,响应没有 data 包装:
调用业务接口
每次 APP 业务请求携带:
X-Gw-*、X-User-Id 等可信身份头。请求体中的资源 ID 不会改变当前用户身份;服务端继续检查应用用户范围、用户资格、资源归属、权限、额度和限流。
业务请求头(如 Content-Type、If-Match、Idempotency-Key、Last-Event-ID)按单接口说明设置;认证头只在本文维护。
请求追踪
APP 接口统一在成功和失败响应的 HTTP 头中返回 X-Request-Id,包括无正文响应、SSE 连接及 WebSocket 握手。服务端访问日志使用同值的 request_id;反馈问题时请提供该值、请求方法、接口路径及发生时间。鉴权拒绝或网关故障发生在业务服务执行之前时,应以该 ID 查询入口日志,不能据此推断业务已执行。
调用方可以在 HTTP 请求头中传入 X-Request-Id。合法值为 1~128 位 ASCII 字母、数字、连字符、下划线或点;未传入或格式不合法时由入口或服务端生成。始终记录实际响应头返回的值,网关可能按自身策略生成请求 ID。追踪标识不代替认证、资源 ID 或 Idempotency-Key。
浏览器通过 response.headers.get('X-Request-Id') 读取;APP 跨域入口允许该请求头并暴露对应响应头。SSE 使用 fetch 返回的 Response 读取本次连接的 ID,重连按新的 HTTP 请求处理,事件 ID 与游标另行保存。浏览器原生 WebSocket API 无法读取握手响应头,需通过浏览器网络面板查看;服务端 WebSocket 客户端可以读取握手响应。
不要依赖所有响应正文都有 trace_id、traceId、request_id 或 requestId。它们按各接口的既有结构返回,内部链路 trace_id 也可能与请求 ID 不同。反馈表单的 request_id 及正文的 requestId 用于关联截图与反馈提交,可以跨多次 HTTP 请求复用,不是统一追踪头。对象存储直传地址使用存储服务自己的响应和请求标识。
客户后台与前端的连接
浏览器直连时,客户后台只负责验证当前用户、映射 QID 并申请凭据;HTTP、SSE 和三个 WS 的业务流量不经过客户后台。API Key 始终留在后台。下述同源端点是客户自行实现的接口,不是 QwenWork 提供的接口:
| 项目 | 客户后台约定 |
|---|---|
| 请求 | POST /api/app-token,无请求体,不接受前端指定 QID |
| 当前用户 | 先验证客户系统的登录身份及请求来源,再从可信账号绑定读取 QID |
| 上游调用 | 使用后台 API Key 调用前述申请接口,按环境、应用和当前用户缓存及合并并发申请 |
| 成功响应 | 200,返回 token_type、access_token、expires_in;从缓存返回时 expires_in 必须是剩余秒数 |
| 缓存控制 | Cache-Control: no-store,不记录凭据正文 |
| 失败 | 未登录返回 401;上游拒绝或暂不可用应保留可区分的错误状态,不返回空成功结果 |
app-client.js 中,即构成快速开始使用的完整客户端模块。先将 APP_BASE_URL 替换为实际环境的 HTTPS Origin,并实现上表的同源后台接口。客户站点若对 POST 有额外的请求校验要求,须在同源请求中按自身约定补齐;不要将这些站点专用头转发到 APP 接口。
统一请求封装
各接口页的 JavaScript 示例使用下面的 appRequest,只展示业务路径、参数及请求头。调用方在此统一处理认证;不要将此封装用于对象存储的上传或下载地址。
有效期与重新申请
- 最长 7 天,以每次返回的
expires_in实际秒数为准。从申请发起时间保守计时,并预留提前量。 - 到期前重新按 QID 申请。新申请不延长或撤销旧 Token,多个有效会话可以并存。
- 公开接口不返回 Refresh Token,不提供刷新或单 Token 撤销操作。
- 按环境、组织、应用、QID 隔离缓存,并合并同一用户的并发申请。新凭据取得后再替换本地值;申请失败不主动丢弃仍有效的旧值。
- 停用或轮换原 API Key 不直接作废已发 Token;应用停用、权限收回、用户范围或资格变化会在访问时重新检查。
- 退出或切换客户账号时清理本地凭据及连接;清理本地状态不等于服务端撤销。
浏览器、SSE 与 WebSocket
本版本 APP HTTP/SSE 入口允许任意 HTTP/HTTPS 网页来源的非凭据模式跨域访问。配置中的允许来源为 *;实际响应的 Access-Control-Allow-Origin 可以是 *,也可以由网关返回与请求 Origin 匹配的具体来源,两种形式都适用于这里的接入方式,不能要求响应值一定是星号。Authorization 明确列入允许的请求头,不启用 Access-Control-Allow-Credentials。浏览器支持星号;限制是跨域请求使用 credentials: 'include' 时不能配合星号。本方案对 APP 业务请求使用 credentials: 'omit',显式设置的认证头仍会发送,不携带站点登录状态。同源的客户后台凭据接口使用上一节的 same-origin,两类请求不要混淆。
部署须同步本版本的 IAM、业务服务和网关配置。浏览器 OPTIONS 预检不携带用户凭据,合规预检不执行登录校验,也不获得用户身份;实际请求仍完整校验凭据及资源权限。401、403 和限流等响应也支持前端读取。此规则仅覆盖 APP 用户接口,不开放管理接口或登录入口;对象存储的跨域配置仍独立维护。
SSE 使用带认证头的 fetch 流式读取,并按事件接口的游标规则恢复。浏览器原生 EventSource 不能自定义认证头,不能直接用于本方案;fetch 不会自动重连,也不会自动保存或发送 Last-Event-ID。客户端须解析完整 SSE 帧,成功处理 session_event 后保存该帧显式 id,重连时自行设置 Last-Event-ID。不把网络读取块当成事件,不从序号间隙推断丢失。cursor 与 Last-Event-ID 同传必须一致,否则返回 422。
客户服务端 WebSocket 客户端继续在握手时设置认证头。浏览器使用子协议传递同一用户 Access Token,仅支持聊天、通知和语音三个路径: