批量开启关闭成员个人 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和脱敏请求。 |