通过 API 配置 QwenWork 管理后台
按应用权限项授权后，调用单接口页面中的 Method、Path 与请求示例完成基础配置。
- 独立 Scope：45
- 接口操作：114
- 权限类型：read / manage / execute
开始调用
- 创建应用：在开放平台创建或选择应用。
- 授权权限项：按用途独立勾选需要的读取、管理或执行权限项。
- 创建 API Key：凭据只在创建成功时完整展示，请立即安全保存。
- 构造请求：按接口文档构造请求，并使用请求 ID 排查问题。
认证方式
API Key、Scope 与组织边界。
通用约定
Host、格式与请求追踪。
错误处理
通用状态码与排查顺序。
认证方式
服务端应用使用开放平台创建的 API Key 调用接口。API Key 代表应用身份，服务端据此确定可信组织和应用已获授权的 Scope。
认证与请求头
所有接口共享以下请求头；单接口页面会按 Method 和请求体列出当前接口实际需要的请求头。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
Authorization | header | string | 是 | 应用 API Key，使用 Bearer 方式传递。 | Bearer <API_KEY> |
X-Request-Id | header | string | 否 | 可选的调用追踪标识；未传入时由服务端生成。 | req-20260831-001 |
Content-Type | header | string | 有 JSON 请求体时 | 请求体媒体类型，固定为 application/json。 | application/json |
Idempotency-Key | header | string | 按单接口文档 | 部分写接口要求的幂等键，长度为 1–128 个可打印 ASCII 字符；相同输入重试时复用原值。 | idem-20260831-001 |
API Key 和其他密钥只能保存在服务端密钥系统中，不得写入浏览器代码、日志、文档或截图。
错误处理
先按 HTTP 状态和稳定业务错误码判断认证、授权、参数、资源或依赖服务问题。
错误码
业务服务错误响应使用统一的 error、detail、code 和可选 details 字段。请求追踪标识通过响应头 X-Request-Id 返回，不在响应正文中。下表只列出当前代码已明确实现的公共或代表性错误码。
| HTTP | 错误类型 | 错误码 | 说明 | 可重试 |
|---|---|---|---|---|
| 400 | BadRequest | request_validation_failed | Content-Type、JSON、revision 等请求格式无效。 | 否 |
| 401 | Unauthorized | openapi_invalid_api_key | API Key 缺失或无效。 | 否 |
| 403 | Forbidden | openapi_scope_denied | API Key 未获得当前接口要求的独立 Scope。 | 否 |
| 404 | NotFound | authn_openapi_not_enabled | OpenAPI 接口未启用或未在网关目录注册。 | 否 |
| 404 | NotFound | department_not_found | 指定部门不存在；这是当前部门接口已实现的资源错误码示例。 | 否 |
| 422 | UnprocessableEntity | request_validation_failed | UUID、分页、字段或 Idempotency-Key 等语义校验失败。 | 否 |
| 503 | ServiceUnavailable | iam_openapi_execution_unavailable | IAM 内部执行链路或相关 OpenAPI 能力暂时不可用。 | 是 |
错误响应示例
{
"error": "UnprocessableEntity",
"detail": "Idempotency-Key is required.",
"code": "request_validation_failed"
}排查与重试顺序
先校验请求格式和 API Key，再核对接口 Scope，随后确认资源状态。仅在 503 或明确可重试的网关错误下退避重试；写接口必须复用原 Idempotency-Key 和完全相同的请求内容。使用响应头 X-Request-Id 关联日志和排查调用链。