跳转至

批量开启关闭成员个人 API Key



POST /api/v1/workspace/member/personal_api_key/enable/modify

概述

批量开启或关闭成员在当前工作空间使用个人API Key的能力。

调用前和使用步骤

从工作空间成员列表取得成员UUID,提交非空accountUUIDs和0/1开关。账号会去重并忽略空值,目标必须是当前空间具有直接或继承角色的有效成员;owner不能被关闭。会保存成员开关,并同步启用/禁用已有用户及智能体个人Key记录、清理对应鉴权缓存;开启不会创建或返回密钥,已删除密钥不会据此重建。返回updated是本次去重后的目标成员数量,不是实际发生状态变化的Key数。随后查询成员列表的enablePersonalAPIKey确认开关,实际使用还须满足成员角色与接口权限。成员关系、角色、令牌和缓存等处理可能分步保存;异常或超时后先读取成员及角色状态,再决定重试。

请求头

参数名 类型 必选 说明
DF-API-KEY string Y 工作空间的 OpenAPI 鉴权凭据。
例子: <DF-API-KEY>
获取或填写方式: 从目标工作空间的 API Key 管理获取有该操作权限的 OpenAPI Key。

Body 请求参数

参数名 类型 必选 说明
accountUUIDs[*] string 数组中的单个字符串标识。
例子: acnt_example
获取或填写方式: 从工作空间成员列表的content.data[].uuid取得当前空间成员账号UUID。不是API Key UUID或邮箱。
accountUUIDs array Y 目标账号UUID数组,传入同一工作空间的实际成员,使用非空字符串。
允许 null: False
例子: ["acnt_example"]
获取或填写方式: 从工作空间成员列表的content.data[].uuid取得当前空间成员账号UUID。不是API Key UUID或邮箱。
enablePersonalAPIKey integer Y 必填整数,只允许0或1;不是JSON布尔或字符串。
允许 null: False
可选值: [0, 1]
例子: 0
获取或填写方式: 需要禁止目标成员使用本空间个人Key填0,允许填1。

参数补充说明

使用当前公开参数声明的整数0/1。控制器兼容的其他类型不作为公开调用格式;此接口不返回任何密钥内容。

请求例子

curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/personal_api_key/enable/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"accountUUIDs":["acnt_example"],"enablePersonalAPIKey":0}'

响应

HTTP 200,application/json。下方示例展示可直接读取的主要字段。

字段 类型 说明
content.updated integer 本次处理的去重非空成员数量。
content.declaration object 或 null 工作空间公共声明。
{
  "code": 200,
  "content": {
    "updated": 1,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

错误响应

鉴权、限流和公共请求错误参见公共错误定义。

HTTP 状态 errorCode 触发条件 消息或响应说明 处理方式
406 ft.ParameterValidationFailed 请求字段缺失,或字段值违反声明的校验条件 参数解析失败 核对参数位置、字段名、类型和取值。
400 ft.RequestJsonFormatError 请求 JSON 语法无效 请求 JSON 格式错误 按 content.reason、line、column 修正 JSON。
400 ft.JsonFormatError JSON顶层不是对象 部分 json 文件格式错误 提交单个JSON对象。
406 ft.MissingParameters 账号数组为空或缺少开关字段 参数缺失 提交至少一个成员UUID并提供enablePersonalAPIKey。
404 ft.NotFoundAccount 账号不存在、状态不符合要求或未找到本空间有效角色 未找到指定账号 从当前空间成员列表重新取得账号,核对直接及继承角色。
403 ft.Forbidden 尝试关闭owner的个人API Key 您无权限操作 保留owner开关,调整其他成员。
500 ft.InternalServerError 数据保存、关联资源或缓存处理失败 内部错误 先核对成员和权限当前状态,再决定重试;持续失败提供traceId和脱敏请求。

文档评价

文档内容是否对您有帮助?