权限类型:read / manage / execute
开始调用
创建应用:在开放平台创建或选择应用。
授权权限项:按用途独立勾选需要的读取、管理或执行权限项。
创建 API Key:凭据只在创建成功时完整展示,请立即安全保存。
构造请求:按接口文档构造请求,并使用请求 ID 排查问题。
认证方式:API Key、Scope 与组织边界。
通用约定:Host、格式与请求追踪。
错误处理:通用状态码与排查顺序。
认证方式
服务端应用使用开放平台创建的 API Key 调用接口。API Key 代表应用身份,服务端据此确定可信组织和应用已获授权的 Scope。
认证与请求头
所有接口适用公共认证与追踪请求头。Authorization 必填,X-Request-Id 可选;Idempotency-Key 仅在单接口参数表明确声明时适用,是否必填以该接口为准。
读取(read)、管理(manage)和执行(execute)权限互不隐含,必须按所调用接口分别授权。
名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
| header | string | 是 | 应用 API Key,使用 Bearer 方式传递。 |
|
| header | string | 否 | 可选的调用追踪标识;未传入时由服务端生成。 |
|
| header | string | 按单接口请求体 | 按单接口声明设置媒体类型;JSON 使用 application/json,文件上传按该接口使用 multipart/form-data,勿将 JSON 头套用于上传。 |
|
| header | string | 按单接口文档 | 仅用于单接口明确支持的幂等请求;是否必填、长度及字符限制以该接口为准,相同输入重试时复用原值。 |
|
API Key 和其他密钥只能保存在服务端密钥系统中,不得写入浏览器代码、日志、文档或截图。
错误处理
先按 HTTP 状态和稳定业务错误码判断认证、授权、参数、资源或依赖服务问题。
错误码
业务服务错误响应使用 error、detail、code 和可选 details 字段。
请求追踪标识通过响应头 X-Request-Id 返回;经公共错误中间件处理且请求上下文中已有追踪标识时,错误正文还可能包含可选的 request_id(string)。
它不是成功响应的通用必填字段,也不能与审批等接口中同名的业务申请 ID 混淆。
HTTP | 错误类型 | 错误码 | 说明 | 可重试 |
400 |
|
| Content-Type、JSON、revision 等请求格式无效。 | 否 |
401 |
|
| API Key 缺失或无效。 | 否 |
403 |
|
| API Key 未获得当前接口要求的独立 Scope。 | 否 |
404 |
|
| OpenAPI 接口未启用或未在网关目录注册。 | 否 |
404 |
|
| 指定部门不存在;这是当前部门接口已实现的资源错误码示例。 | 否 |
422 |
|
| UUID、分页、字段或 Idempotency-Key 等语义校验失败。 | 否 |
503 |
|
| IAM 内部执行链路或相关 OpenAPI 能力暂时不可用。 | 是 |
错误响应示例
{
"error": "UnprocessableEntity",
"detail": "Idempotency-Key is required.",
"code": "request_validation_failed"
}
排查与重试顺序
先校验请求格式和 API Key,再核对接口 Scope,随后确认资源状态。
仅在 503 或明确可重试的网关错误下退避重试;仅对明确支持幂等重放的接口复用原 Idempotency-Key 和完全相同的请求内容;其他写操作应先查询实际结果,再按该接口说明决定是否重试。
使用响应头 X-Request-Id 关联日志和排查调用链。
字段表阅读约定
请求字段的“必填”表示调用方必须提交;响应字段的“必填”表示对应响应分支保证包含该键,不是需要填写的参数。
必填性与可空性分别判断:可省略不等于允许
null,允许null也不等于可以省略。以字段表的“必填”和“类型”为准。嵌套字段要求仅在父对象存在且非
null时适用;对象数组的字段要求逐个应用于非null元素,仅凭子字段必填不能推断数组非空;minItems 等数组数量约束仍独立适用。数组本身和数组元素是否允许null分别以其类型为准。可选对象的出现条件、条件必填及特殊业务约束在对应接口字段说明中列明;同名字段在不同响应分支的含义以该分支为准。
{key}、{locale} 等路径表示动态字典键,[] 表示数组元素;具体允许的键和扩展属性以接口说明为准。 示例域名及 <...> 均为占位符,调用前替换为实际地址和业务值。版本号使用查询返回的当前值;配置发布前先读取现有配置,按接口的合并或替换语义保留不需修改的字段。示例不包含真实凭据。
公共错误响应
仅在状态表明确引用本结构时适用。特殊业务详情见对应接口;不得将冲突或同步恢复字段视为所有错误共有字段。request_id 是错误中间件可能附加的可选追踪字段,现有生成协议未声明,参见本页错误处理说明。
公共错误字段
名称 | 类型 | 必填 | 说明 | 示例 |
|
| 是 | 错误说明;客户端分支应使用 code。 |
|
|
| 是 | 稳定的 HTTP 错误类型。 |
|
通用错误
复用结构:见本文“公共错误字段”
名称 | 类型 | 必填 | 说明 | 示例 |
|
| 否 | 稳定业务错误码;没有业务码时可省略。 |
|
|
| 否 | 仅在该错误分支有结构化详情时出现。 |
|
details
字段 | 类型 | 必填 | 说明 |
|
| 否 | 相关的公开请求字段名。 |
|
| 否 | 校验失败原因。 |
|
| 否 | 建议修正值或处理方式。 |
公共错误示例
以下仅示意公共必填字段;可选业务码、详情及追踪标识按实际错误场景返回。
{
"error": "Bad Request",
"detail": "Request validation failed"
}
用户写入的同步等待与重试
适用于创建、更新、删除用户、调整用户席位/状态及入组织/席位申请审批:本地业务提交后最多等待 10 秒,同步确认成功立即返回该接口的成功响应,不固定等待满 10 秒。
同步仍在处理时可能返回 HTTP 503 / iam_openapi_execution_unavailable,具体详情以接口的特殊响应结构为准。
committed=true 表示本地写入已执行,不表示同步完成;不要因此另起一笔写操作。先通过查询接口核对业务状态;声明了幂等键的操作应复用原键和原请求。
提交前校验失败仍按原错误处理;普通 503 不代表已经提交,也不代表已经回滚。