Skip to main content

认证接入

千问办公企业旗舰版开发者文档:认证接入。

接入流程

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”接口。
curl --request POST "$BASE_URL/api/openapi/v1/app-user-tokens" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"qid":"11111111-1111-4111-8111-111111111111"}'
成功返回 200 和 Cache-Control: no-store,响应没有 data 包装:
{"token_type":"Bearer","access_token":"<ACCESS_TOKEN>","expires_in":604800}
API Key 仅保存在客户后台,不交给浏览器。颁发接口不是幂等操作:超时或响应丢失时,原会话可能已经创建;再次申请会产生另一独立会话。

调用业务接口

每次 APP 业务请求携带:
Authorization: Bearer <ACCESS_TOKEN>
API Key 不能直接替代用户 Access Token 调用 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;上游拒绝或暂不可用应保留可区分的错误状态,不返回空成功结果
以下三个 JavaScript 代码块依次放到客户站点的 app-client.js 中,即构成快速开始使用的完整客户端模块。先将 APP_BASE_URL 替换为实际环境的 HTTPS Origin,并实现上表的同源后台接口。客户站点若对 POST 有额外的请求校验要求,须在同源请求中按自身约定补齐;不要将这些站点专用头转发到 APP 接口。
const APP_BASE_URL = 'https://your-qwenwork.example.com';
let tokenCache;
let tokenPending;

async function getCurrentAccessToken() {
  if (tokenCache && tokenCache.expiresAt > Date.now() + 30_000) {
    return tokenCache.value;
  }
  if (!tokenPending) {
    tokenPending = (async () => {
      const started = Date.now();
      const response = await fetch('/api/app-token', {
        method: 'POST',
        credentials: 'same-origin',
        cache: 'no-store',
        redirect: 'error',
        signal: AbortSignal.timeout(15_000),
      });
      if (!response.ok) throw new Error('申请凭据失败:' + response.status);
      const result = await response.json();
      if (result.token_type !== 'Bearer' ||
          typeof result.access_token !== 'string' || !result.access_token ||
          !Number.isFinite(result.expires_in) || result.expires_in <= 0) {
        throw new Error('后台返回的凭据格式不正确');
      }
      const expiresAt = started + result.expires_in * 1000;
      if (expiresAt <= Date.now() + 30_000) throw new Error('凭据剩余有效期不足');
      tokenCache = { value: result.access_token, expiresAt };
      return tokenCache.value;
    })().finally(() => { tokenPending = undefined; });
  }
  return tokenPending;
}

function invalidateCredential() {
  tokenCache = undefined;
}
凭据只放在内存。退出或切换客户账号时先中止请求和关闭连接,再整页重新加载,避免旧账号的在途申请结果进入新账号上下文。业务接口返回 401 后可清除缓存并重新取得凭据,但不能自动重放业务写请求;403 应检查授权,不通过反复申请解决。

统一请求封装

各接口页的 JavaScript 示例使用下面的 appRequest,只展示业务路径、参数及请求头。调用方在此统一处理认证;不要将此封装用于对象存储的上传或下载地址。
function createAppRequest(baseUrl, getAccessToken) {
  const base = new URL(baseUrl);
  return async function appRequest(path, options = {}) {
    const url = new URL(path, base);
    if (url.origin !== base.origin ||
        !url.pathname.startsWith('/api/openapi/app/v1/')) {
      throw new Error('仅允许调用当前环境的 APP 业务接口');
    }
    const headers = new Headers(options.headers);
    headers.set('Authorization', 'Bearer ' + await getAccessToken());
    return fetch(url, {
      ...options,
      headers,
      credentials: 'omit',
      redirect: 'error',
    });
  };
}
// 使用上一节实现的当前用户凭据读取函数。
const appRequest = createAppRequest(APP_BASE_URL, getCurrentAccessToken);
该示例不自动重放业务写请求。发生认证失效时,应先恢复凭据,再根据对应业务接口的幂等与结果查询规则决定是否重试。

有效期与重新申请

  • 最长 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,仅支持聊天、通知和语音三个路径:
async function createAppWebSocket(path) {
  const base = new URL(APP_BASE_URL);
  const url = new URL(path, base);
  const allowed = new Set([
    '/api/openapi/app/v1/sessions/chat-ws',
    '/api/openapi/app/v1/sessions/notify-ws',
    '/api/openapi/app/v1/sessions/voice-input/stream',
  ]);
  if (url.origin !== base.origin || !allowed.has(url.pathname) || url.username || url.password || url.hash) {
    throw new Error('仅允许当前环境的三个 APP WS 接口');
  }
  if (url.protocol !== 'https:') throw new Error('WS 直连要求 HTTPS/WSS');
  url.protocol = 'wss:';
  return new WebSocket(url, [
    'qwenwork.app.v1',
    'qwenwork.auth.' + await getCurrentAccessToken(),
  ]);
}

export { appRequest, createAppWebSocket, invalidateCredential };
两个子协议项必须同时提供且各出现一次;服务端只返回固定协议 qwenwork.app.v1,不回显凭据项。不要同时提供认证头与凭据子协议。无效凭据在升级前拒绝,不自动切换认证方式。语音的 language 查询参数保持原规则,禁止在 URL 中传 Token。 原生 WebSocket 不提供 credentials 选项。即使浏览器自动携带当前站点登录状态,只要提供了凭据子协议,就以该凭据认证,失败时不会使用其他登录状态重试。 部署网关须向 IAM 转发 Sec-WebSocket-Protocol、Sec-WebSocket-Key 和 Sec-WebSocket-Version,再将验证后的身份及认证头传给 WS 服务。Sec-WebSocket-Protocol 含敏感凭据,不得记录原值。WS 不使用 HTTP CORS 预检;HTTP/SSE 仍按前述 CORS 要求配置。 长连接按凭据到期时间截止,并周期复核当前资格。取得新凭据后建立新连接;旧连接不会自动换用新凭据。已提交的后台任务按原业务生命周期执行。

错误与安全

401 检查当前阶段使用的凭据及其期限;403 检查应用授权、用户资格与资源权限;429 按 Retry-After 退避;503 检查配置及依赖,不无限重取凭据。业务错误的响应结构以单接口文档为准。 凭据及认证请求头不得写入日志、截图、工单或请求 URL;颁发响应不进入共享缓存。对于结果不明的任务创建、消息发送等写操作,先查询业务结果或使用已有幂等机制,不能因为取得新凭据就盲目重放。