HTTP API-成员管理：专业版使用文档

1. 接入约定

正式环境 Base URL：https://app.dicloak.com/gin

• 鉴权：请求头 X-HTTP-KEY，使用当前团队的 HTTP API Key。
• 数据格式：JSON，请求体使用 Content-Type: application/json，字段使用 snake_case，ID 使用字符串。
• 成功判断：code=0 为成功；非 0 为失败。HTTP 200 不代表业务成功，参数解析错误可返回 HTTP 400。
• 示例：cURL 使用 Bash 语法，Key、ID、密码、邮箱和到期日期需替换为实际值。

2. 接口目录

章节	方法	路径	功能
3	GET	/v1/api/request/member/group	查询成员分组
4	GET	/v1/api/request/member	查询成员列表
5	GET	/v1/api/request/member/{id}	查询成员详情
6	POST	/v1/api/request/member	创建成员
7	PATCH	/v1/api/request/member/{id}	部分修改成员资料
8	PUT	/v1/api/request/member/{id}	完整替换成员基础资料
9	GET	/v1/api/request/member/{id}/expiration	查询到期停用配置
10	PATCH	/v1/api/request/member/{id}/expiration	修改到期停用配置
11	DELETE	/v1/api/request/member/{id}	删除成员
12	PATCH	/v1/api/request/member/{id}/password	重置内部成员密码
13	GET	/v1/api/request/member/{id}/permissions	查询成员功能权限
14	GET	/v1/api/request/member/{id}/login-verification	查询内部成员登录验证
15	PATCH	/v1/api/request/member/{id}/login-verification	修改内部成员登录验证
16	POST	/v1/api/request/member/{id}/totp	生成并启用新的 2FA 密钥

3. 查询成员分组

查询当前团队成员分组，将返回的分组 ID 用于创建或修改成员的 member_group_id。

请求地址

GET https://app.dicloak.com/gin/v1/api/request/member/group

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

请求参数

路径参数：无。请求体：无。

参数	类型	必填	说明
page_no	integer	否	页码，默认 1，最小 1。
page_size	integer	否	每页数量，默认 10，范围 1～200。
name	string	否	按成员分组名称精确匹配。

请求示例

curl --get 'https://app.dicloak.com/gin/v1/api/request/member/group' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --data-urlencode 'page_no=1' \  --data-urlencode 'page_size=20'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为列表对象，失败时可为 null。
data.list	array	本次返回的数据。
data.total	integer	符合条件的总数量。
data.summary	null	本接口不使用汇总字段。
data.page_token	null	本接口不使用游标分页。
data.list[].id	string	成员分组 ID，填写到 member_group_id。
data.list[].name	string	成员分组名称。
data.list[].remark	string/null	分组备注。

成功响应示例

{  "code": 0,  "msg": "success",  "data": {    "list": [      {        "id": "member_group_001",        "name": "Customer Operations",        "remark": "Customer support permissions"      }    ],    "total": 1,    "summary": null,    "page_token": null  }}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	page_no 或 page_size 的类型、取值范围不正确。
500000	请求处理失败。

错误响应示例：

{  "code": 400009,  "msg": "[page_size] must be an integer",  "data": null,  "next": null}

4. 查询成员列表

分页查询当前团队的内部成员和外部成员。多个筛选条件按 AND 组合，名称和账号使用精确匹配。

请求地址

GET https://app.dicloak.com/gin/v1/api/request/member

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

请求参数

路径参数：无。请求体：无。

参数	类型	必填	说明
page_no	integer	否	默认 1，最小 1。
page_size	integer	否	默认 10，范围 1～200。
id	string	否	成员 ID，精确匹配。
account	string	否	内部账号或外部邮箱，精确匹配。
name	string	否	成员显示名称，精确匹配。
type	string	否	INTERNAL / EXTERNAL；省略查询两类。
status	string	否	ENABLED / DISABLED；按包含到期因素的有效状态筛选。
authority	string	否	SUPER_ADMIN / ADMIN / MANAGER / MEMBER。
member_group_id	string	否	当前团队成员分组 ID。
profile_group_id	string	否	当前团队 Profile 分组 ID；包含明确授权和全部分组授权的成员。

请求示例

curl --get 'https://app.dicloak.com/gin/v1/api/request/member' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --data-urlencode 'page_no=1' \  --data-urlencode 'page_size=20' \  --data-urlencode 'type=INTERNAL' \  --data-urlencode 'status=ENABLED'

按外部邮箱精确查询：

curl --get 'https://app.dicloak.com/gin/v1/api/request/member' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --data-urlencode 'account=partner@example.com' \  --data-urlencode 'page_no=1' \  --data-urlencode 'page_size=20'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为列表对象，失败时可为 null。
data.list	array	本次返回的数据。
data.total	integer	符合条件的总数量。
data.summary	null	本接口不使用汇总字段。
data.page_token	null	本接口不使用游标分页。
data.list[].id	string	成员 ID。
data.list[].name	string	成员显示名称。
data.list[].account	string	INTERNAL 为登录账号；EXTERNAL 为个人邮箱。
data.list[].type	string	INTERNAL / EXTERNAL。
data.list[].status	string	ENABLED / DISABLED；包含到期状态，固定到期时间已过视为 DISABLED。
data.list[].authority	string	SUPER_ADMIN（超级管理员）/ ADMIN（管理员）/ MANAGER（经理）/ MEMBER（普通成员，英文 UI 为 Staff）。
data.list[].member_group_id	string/null	功能权限成员分组 ID，不是成员身份。
data.list[].member_group_name	string/null	成员分组名称。
data.list[].manager	object/null	上级经理；未分配时为 null。
data.list[].manager.id	string	经理成员 ID。
data.list[].manager.name	string	经理显示名称。
data.list[].all_profile_groups	boolean	是否拥有全部 Profile 分组访问权。
data.list[].profile_group_list	array	指定授权的 Profile 分组；all_profile_groups=true 时返回 []。
data.list[].profile_group_list[].id	string	Profile 分组 ID，不是单个 Profile ID。
data.list[].profile_group_list[].name	string	Profile 分组名称。
data.list[].disuse_remaining_time	integer/null	距停用的剩余毫秒数，可为负数或 null；成员状态以 status 为准。
data.list[].remark	string/null	备注，空备注返回 null。
data.list[].create_time	string/null	创建时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.list[].update_time	string/null	修改时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。

成功响应示例

{  "code": 0,  "msg": "success",  "data": {    "list": [      {        "id": "member_001",        "name": "Alice",        "account": "alice001",        "type": "INTERNAL",        "status": "ENABLED",        "authority": "MEMBER",        "member_group_id": "member_group_001",        "member_group_name": "Customer Operations",        "manager": {          "id": "manager_001",          "name": "Team Manager"        },        "all_profile_groups": false,        "profile_group_list": [          {            "id": "profile_group_001",            "name": "Customer Profiles"          }        ],        "remark": "Customer Operations",        "create_time": "2026-09-24 10:00:00",        "update_time": "2026-09-24 10:00:00",        "disuse_remaining_time": null      }    ],    "total": 1,    "summary": null,    "page_token": null  }}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	page_no、page_size 的类型或范围错误，或 authority 取值不正确。
400017	type 或 status 枚举不合法。
300001	用于筛选的成员分组或 Profile 分组不存在于当前团队。
500000	请求处理失败。

错误响应示例：

{  "code": 400009,  "msg": "[page_no] must be an integer",  "data": null,  "next": null}

5. 查询成员详情

查询当前团队指定成员的基础资料、分组授权和完整到期配置。

请求地址

GET https://app.dicloak.com/gin/v1/api/request/member/{id}

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

路径参数

参数	类型	必填	说明
id	string	是	当前团队成员 ID；

Query 参数：无。

请求体

无。

请求示例

curl --request GET 'https://app.dicloak.com/gin/v1/api/request/member/member_001' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.id	string	成员 ID。
data.name	string	成员显示名称。
data.account	string	INTERNAL 为登录账号；EXTERNAL 为个人邮箱。
data.type	string	INTERNAL / EXTERNAL。
data.status	string	ENABLED / DISABLED；包含到期状态，固定到期时间已过视为 DISABLED。
data.authority	string	SUPER_ADMIN（超级管理员）/ ADMIN（管理员）/ MANAGER（经理）/ MEMBER（普通成员）。
data.member_group_id	string/null	功能权限成员分组 ID，不是成员身份。
data.member_group_name	string/null	成员分组名称。
data.manager	object/null	上级经理；未分配时为 null。
data.manager.id	string	经理成员 ID。
data.manager.name	string	经理显示名称。
data.all_profile_groups	boolean	是否拥有全部 Profile 分组访问权。
data.profile_group_list	array	指定授权的 Profile 分组；all_profile_groups=true 时返回 []。
data.profile_group_list[].id	string	Profile 分组 ID，不是单个 Profile ID。
data.profile_group_list[].name	string	Profile 分组名称。
data.remark	string/null	备注，空备注返回 null。
data.create_time	string/null	创建时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.update_time	string/null	修改时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.expiration	object	到期停用配置；关闭时仅包含 enabled=false。
data.expiration.enabled	boolean	是否启用到期停用。
data.expiration.time_zone	string	开启时返回，IANA 时区，如 America/New_York。
data.expiration.mode	string	开启时返回：INSTANT 固定到期；LOGIN_START 首次登录后计时。
data.expiration.expires_at	string	仅 INSTANT 返回；time_zone 当地时间，格式 yyyy-MM-dd HH:mm。
data.expiration.days	integer	仅 LOGIN_START 返回；首次登录后有效天数。

成功响应示例

{  "code": 0,  "msg": "success",  "data": {    "id": "member_001",    "name": "Alice",    "account": "alice001",    "type": "INTERNAL",    "status": "ENABLED",    "authority": "MEMBER",    "member_group_id": "member_group_001",    "member_group_name": "Customer Operations",    "manager": {      "id": "manager_001",      "name": "Team Manager"    },    "all_profile_groups": false,    "profile_group_list": [      {        "id": "profile_group_001",        "name": "Customer Profiles"      }    ],    "expiration": {      "enabled": true,      "time_zone": "America/New_York",      "mode": "INSTANT",      "expires_at": "2099-12-31 23:59"    },    "remark": "Customer Operations",    "create_time": "2026-09-24 10:00:00",    "update_time": "2026-09-24 10:00:00"  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
300001	成员不存在、已删除，或不属于当前团队。
500000	请求处理失败。

错误响应示例：

{  "code": 300001,  "msg": "id does not identify an existing member in the current team",  "data": null,  "next": null}

6. 创建成员

创建内部账号及团队成员，或将外部个人账号加入当前团队。成功后保存 data.id，后续成员操作使用该 ID。

请求地址

POST https://app.dicloak.com/gin/v1/api/request/member

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。
Content-Type	string	是	固定为 application/json。

请求参数

路径参数：无。Query 参数：无。

JSON Body：基础字段

参数	类型	必填	说明
name	string	是	非空，最多 20 字符；当前团队内不能重名。
account	string	是	INTERNAL：6～20 位英文字母或数字，不允许空格；EXTERNAL：有效邮箱。
password	string	INTERNAL 必填	8～25 字符，至少一个英文字母和一个数字，不允许首尾空白；通过 HTTPS 提交原始密码字符串，请勿预先进行哈希、编码或加密转换。EXTERNAL 应省略。
type	string	是	INTERNAL / EXTERNAL；创建后不可通过资料接口修改。
authority	string	是	ADMIN / MANAGER / MEMBER；
member_group_id	string	是	当前团队存在、启用且可分配的成员分组 ID。
status	string	否	ENABLED / DISABLED；默认 ENABLED。
manager_id	string	否	仅 authority=MEMBER 可设置，须为当前团队已启用的 MANAGER 成员 ID。省略表示无上级经理。
all_profile_groups	boolean	否	ADMIN 默认 true，其他身份默认 false；ADMIN 必须为 true。
profile_group_ids	array of string	否	当前团队的 Profile 分组 ID 数组，默认 []；all_profile_groups=true 时须为空；ID 不得为空或重复。
expiration	object	否	省略关闭到期停用；提交时必须提供 enabled，开启时提供完整模式配置。
login_verification	object	否	仅 INTERNAL 可设置；省略关闭邮箱验证和 2FA。提交时至少包含 email/check_email/check_2fa/trigger 中一项，不能为 null。
remark	string/null	否	最多 200 字符；省略表示无备注。

JSON Body：expiration 全部字段

参数	类型	必填	说明
expiration.enabled	boolean	对象存在时必填	false 时对象中只能有 enabled；true 时必须提供时区、模式及日期或天数；配置字段不接受 null。
expiration.time_zone	string	开启时必填	IANA 时区，如 America/New_York、Europe/London、Asia/Shanghai。
expiration.mode	string	开启时必填	INSTANT：指定时间停用；LOGIN_START：首次登录后计时。
expiration.expires_at	string	INSTANT 开启或切换时必填	当地时间，精确到分钟；格式 yyyy-MM-dd HH:mm，也接受 yyyy-MM-dd HH:mm:ss（忽略秒）。必须为未来时间，不可同时传 days。
expiration.days	integer	LOGIN_START 开启或切换时必填	1～36500，仅可在首次激活前设置，不可同时传 expires_at；续期使用 expires_at。

JSON Body：login_verification 全部字段

参数	类型	必填	说明
login_verification.check_email	boolean	否	默认 false，不接受 null；开启时 email 必须有效。
login_verification.email	string/null	否	验证码接收邮箱，不是登录账号；允许更新且无需验证码。邮箱验证开启时不能清空。
login_verification.check_2fa	boolean	否	默认 false；true 开启 2FA，不接受 null。密钥通过响应 secret_2fa 获取，不允许在请求中提交。
login_verification.trigger	object	否	默认 EVERY_LOGIN；提交时必须为完整触发配置，不能为 null。
login_verification.trigger.mode	string	提交 trigger 时必填	EVERY_LOGIN：每次登录团队验证；DEVICE_OR_INTERVAL：换设备或达到时间间隔后验证。
login_verification.trigger.interval	integer	间隔模式必填	1～168。EVERY_LOGIN 不允许提交。
login_verification.trigger.unit	string	间隔模式必填	HOUR / DAY。EVERY_LOGIN 不允许提交。
login_verification.trigger.logout_on_timeout	boolean	否	间隔模式省略时为 false；true 表示到时自动退出。EVERY_LOGIN 不允许提交，不能为 null。

请求示例：内部成员

curl --request POST 'https://app.dicloak.com/gin/v1/api/request/member' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "name": "Alice",  "account": "alice001",  "password": "ExamplePass2026!",  "type": "INTERNAL",  "authority": "MEMBER",  "member_group_id": "member_group_001",  "status": "ENABLED",  "manager_id": "manager_001",  "all_profile_groups": false,  "profile_group_ids": [    "profile_group_001"  ],  "expiration": {    "enabled": true,    "time_zone": "America/New_York",    "mode": "INSTANT",    "expires_at": "2099-12-31 23:59"  },  "login_verification": {    "check_email": true,    "email": "alice.verify@example.com",    "check_2fa": true,    "trigger": {      "mode": "DEVICE_OR_INTERVAL",      "interval": 7,      "unit": "DAY",      "logout_on_timeout": false    }  },  "remark": "Customer Operations"}'

请求示例：外部成员

curl --request POST 'https://app.dicloak.com/gin/v1/api/request/member' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "name": "Partner",  "account": "partner@example.com",  "type": "EXTERNAL",  "authority": "MEMBER",  "member_group_id": "member_group_001",  "status": "ENABLED",  "all_profile_groups": false,  "profile_group_ids": [    "profile_group_001"  ],  "expiration": {    "enabled": false  },  "remark": "External partner"}'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.id	string	成员 ID。
data.name	string	成员显示名称。
data.account	string	INTERNAL 为登录账号；EXTERNAL 为个人邮箱。
data.type	string	INTERNAL / EXTERNAL。
data.status	string	ENABLED / DISABLED；包含到期状态，固定到期时间已过视为 DISABLED。
data.authority	string	SUPER_ADMIN（超级管理员）/ ADMIN（管理员）/ MANAGER（经理）/ MEMBER（普通成员，英文 UI 为 Staff）。
data.member_group_id	string/null	功能权限成员分组 ID，不是成员身份。
data.member_group_name	string/null	成员分组名称。
data.manager	object/null	上级经理；未分配时为 null。
data.manager.id	string	经理成员 ID。
data.manager.name	string	经理显示名称。
data.all_profile_groups	boolean	是否拥有全部 Profile 分组访问权。
data.profile_group_list	array	指定授权的 Profile 分组；all_profile_groups=true 时返回 []。
data.profile_group_list[].id	string	Profile 分组 ID，不是单个 Profile ID。
data.profile_group_list[].name	string	Profile 分组名称。
data.remark	string/null	备注，空备注返回 null。
data.create_time	string/null	创建时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.update_time	string/null	修改时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.expiration	object	到期停用配置；关闭时仅包含 enabled=false。
data.expiration.enabled	boolean	是否启用到期停用。
data.expiration.time_zone	string	开启时返回，IANA 时区，如 America/New_York。
data.expiration.mode	string	开启时返回：INSTANT 固定到期；LOGIN_START 首次登录后计时。
data.expiration.expires_at	string	仅 INSTANT 返回；time_zone 当地时间，格式 yyyy-MM-dd HH:mm。
data.expiration.days	integer	仅 LOGIN_START 返回；首次登录后有效天数。
data.login_verification	object	创建 INTERNAL 时返回；EXTERNAL 不返回。
data.login_verification.check_email	boolean	是否开启邮箱验证。
data.login_verification.email	string	仅 check_email=true 时返回验证码接收邮箱。
data.login_verification.check_2fa	boolean	是否开启 2FA。
data.login_verification.secret_2fa	string	仅 check_2fa=true 时返回；这是验证器密钥，不是动态验证码。
data.login_verification.trigger	object	当前验证触发配置。
data.login_verification.trigger.mode	string	EVERY_LOGIN / DEVICE_OR_INTERVAL。
data.login_verification.trigger.interval	integer	仅 DEVICE_OR_INTERVAL 返回；间隔 1～168。
data.login_verification.trigger.unit	string	仅 DEVICE_OR_INTERVAL 返回；HOUR / DAY。
data.login_verification.trigger.logout_on_timeout	boolean	仅 DEVICE_OR_INTERVAL 返回；达到间隔后是否自动退出。

响应头：Cache-Control: no-store。不会返回 password。

成功响应示例：内部成员

{  "code": 0,  "msg": "success",  "data": {    "id": "member_001",    "name": "Alice",    "account": "alice001",    "type": "INTERNAL",    "status": "ENABLED",    "authority": "MEMBER",    "member_group_id": "member_group_001",    "member_group_name": "Customer Operations",    "manager": {      "id": "manager_001",      "name": "Team Manager"    },    "all_profile_groups": false,    "profile_group_list": [      {        "id": "profile_group_001",        "name": "Customer Profiles"      }    ],    "expiration": {      "enabled": true,      "time_zone": "America/New_York",      "mode": "INSTANT",      "expires_at": "2099-12-31 23:59"    },    "remark": "Customer Operations",    "create_time": "2026-09-24 10:00:00",    "update_time": "2026-09-24 10:00:00",    "login_verification": {      "check_email": true,      "email": "alice.verify@example.com",      "check_2fa": true,      "secret_2fa": "<SERVER_GENERATED_2FA_SECRET>",      "trigger": {        "mode": "DEVICE_OR_INTERVAL",        "interval": 7,        "unit": "DAY",        "logout_on_timeout": false      }    }  },  "next": null}

成功响应示例：外部成员

{  "code": 0,  "msg": "success",  "data": {    "id": "member_external_001",    "name": "Partner",    "account": "partner@example.com",    "type": "EXTERNAL",    "status": "ENABLED",    "authority": "MEMBER",    "member_group_id": "member_group_001",    "member_group_name": "Customer Operations",    "manager": null,    "all_profile_groups": false,    "profile_group_list": [      {        "id": "profile_group_001",        "name": "Customer Profiles"      }    ],    "expiration": {      "enabled": false    },    "remark": "External partner",    "create_time": "2026-09-24 10:00:00",    "update_time": "2026-09-24 10:00:00"  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	必填字段缺失、权限配置冲突、外部成员提交登录验证配置。
400017	内部账号或外部邮箱格式错误、字段超长、外部成员提交密码。
300001	成员分组、Profile 分组或经理不属于当前团队，或引用不存在。
400011	成员分组已停用或不能分配。
300108	团队内成员名称重复。
300131	当前团队内外部成员邮箱重复。
300164	账号不可作为外部个人账号关联或账号已占用。
300165	内部账号已存在。
300133	团队成员额度已满。
300203	密码格式不合法。
300204	时区不合法。
300205	到期时间或天数不合法。
300206	请求分配 SUPER_ADMIN 身份。
500000	请求处理失败。

错误响应示例：

{  "code": 300203,  "msg": "password must be 8-25 characters, contain an English letter and a digit, and have no leading or trailing spaces",  "data": null,  "next": null}

7. 部分修改成员资料

仅修改明确提交的基础资料字段；未提交的字段保留原值。支持内部和外部成员，不支持修改超级管理员。

请求地址

PATCH https://app.dicloak.com/gin/v1/api/request/member/{id}

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。
Content-Type	string	是	固定为 application/json。

路径参数

参数	类型	必填	说明
id	string	是	当前团队成员 ID；支持 INTERNAL、EXTERNAL，不允许修改 SUPER_ADMIN。

Query 参数：无。

JSON Body 参数

至少提交以下八个字段中的一个；空对象 {} 会报错。

参数	类型	必填	说明
name	string	否	非空，最多 20 字符，当前团队内不能重名；省略保持，null 拒绝。
authority	string	否	ADMIN / MANAGER / MEMBER；省略保持，null 拒绝。从 ADMIN 降级须同时传 all_profile_groups 和 profile_group_ids。
status	string	否	ENABLED / DISABLED；省略保持，null 拒绝。
member_group_id	string	否	当前团队启用、可分配的成员分组；省略保持，null 或空白拒绝。
manager_id	string/null	否	仅 authority=MEMBER 可提交，须为当前团队已启用的经理 ID；null 清空，省略保持。
all_profile_groups	boolean	否	是否访问全部 Profile 分组；ADMIN 必须为 true，不接受 null。
profile_group_ids	array of string	否	当前团队的 Profile 分组 ID 数组，完整替换授权集合；[] 清空，null 拒绝，省略保持；all_profile_groups=true 时须为空。
remark	string/null	否	最多 200 字符；null 清空，省略保持。

请求示例：修改分组授权与备注

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "all_profile_groups": false,  "profile_group_ids": [    "profile_group_001"  ],  "remark": "Updated by API"}'

请求示例：停用成员

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "status": "DISABLED"}'

请求示例：管理员降为普通成员

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "authority": "MEMBER",  "all_profile_groups": false,  "profile_group_ids": [    "profile_group_001"  ]}'

请求示例：清空普通成员的经理和备注

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "manager_id": null,  "remark": null}'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.id	string	成员 ID。
data.name	string	成员显示名称。
data.account	string	INTERNAL 为登录账号；EXTERNAL 为个人邮箱。
data.type	string	INTERNAL / EXTERNAL。
data.status	string	ENABLED / DISABLED；包含到期状态，固定到期时间已过视为 DISABLED。
data.authority	string	SUPER_ADMIN（超级管理员）/ ADMIN（管理员）/ MANAGER（经理）/ MEMBER（普通成员，英文 UI 为 Staff）。
data.member_group_id	string/null	功能权限成员分组 ID，不是成员身份。
data.member_group_name	string/null	成员分组名称。
data.manager	object/null	上级经理；未分配时为 null。
data.manager.id	string	经理成员 ID。
data.manager.name	string	经理显示名称。
data.all_profile_groups	boolean	是否拥有全部 Profile 分组访问权。
data.profile_group_list	array	指定授权的 Profile 分组；all_profile_groups=true 时返回 []。
data.profile_group_list[].id	string	Profile 分组 ID，不是单个 Profile ID。
data.profile_group_list[].name	string	Profile 分组名称。
data.remark	string/null	备注，空备注返回 null。
data.create_time	string/null	创建时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.update_time	string/null	修改时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.expiration	object	到期停用配置；关闭时仅包含 enabled=false。
data.expiration.enabled	boolean	是否启用到期停用。
data.expiration.time_zone	string	开启时返回，IANA 时区，如 America/New_York。
data.expiration.mode	string	开启时返回：INSTANT 固定到期；LOGIN_START 首次登录后计时。
data.expiration.expires_at	string	仅 INSTANT 返回；time_zone 当地时间，格式 yyyy-MM-dd HH:mm。
data.expiration.days	integer	仅 LOGIN_START 返回；首次登录后有效天数。

成功响应示例

以下为“修改分组授权与备注”请求的完整成功响应。

{  "code": 0,  "msg": "success",  "data": {    "id": "member_001",    "name": "Alice",    "account": "alice001",    "type": "INTERNAL",    "status": "ENABLED",    "authority": "MEMBER",    "member_group_id": "member_group_001",    "member_group_name": "Customer Operations",    "manager": {      "id": "manager_001",      "name": "Team Manager"    },    "all_profile_groups": false,    "profile_group_list": [      {        "id": "profile_group_001",        "name": "Customer Profiles"      }    ],    "expiration": {      "enabled": true,      "time_zone": "America/New_York",      "mode": "INSTANT",      "expires_at": "2099-12-31 23:59"    },    "remark": "Updated by API",    "create_time": "2026-09-24 10:00:00",    "update_time": "2026-09-24 11:00:00"  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	空请求、不允许的 null、经理或分组授权配置冲突。
400017	名称或备注超长等格式错误。
300001	成员或关联分组/经理不存在于当前团队。
400011	成员分组已停用或不能分配。
300108	成员名称重复。
300205	成员到期规则已过期，需要先续期或关闭到期再恢复。
300206	修改超级管理员或分配 SUPER_ADMIN。
300099	请求暂时无法处理，请稍后重试。
500000	请求处理失败。

错误响应示例：

{  "code": 400009,  "msg": "request_body must contain at least one editable member field",  "data": null,  "next": null}

8. 完整替换成员基础资料

提交完整可编辑基础资料。缺少必填字段会报错；可选的经理和备注省略时会清空。支持内部和外部成员，不支持修改超级管理员。

请求地址

PUT https://app.dicloak.com/gin/v1/api/request/member/{id}

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。
Content-Type	string	是	固定为 application/json。

路径参数

参数	类型	必填	说明
id	string	是	当前团队成员 ID；支持 INTERNAL、EXTERNAL，不允许修改 SUPER_ADMIN。

Query 参数：无。

JSON Body 参数

参数	类型	必填	说明
name	string	是	非空，最多 20 字符，团队内不可重名。
authority	string	是	ADMIN / MANAGER / MEMBER；不允许 SUPER_ADMIN。
status	string	是	ENABLED / DISABLED。
member_group_id	string	是	当前团队启用且可分配的成员分组 ID。。
all_profile_groups	boolean	是	ADMIN 必须 true；是否访问全部 Profile 分组。
profile_group_ids	array of string	是	当前团队的 Profile 分组 ID 数组；完整替换授权集合，不可为 null；all_profile_groups=true 时必须传 []。
manager_id	string/null	否	仅 MEMBER 可设置非空值；须为当前团队已启用的 MANAGER；省略或 null 会清空。
remark	string/null	否	最多 200 字符；省略或 null 会清空。

请求示例

curl --request PUT 'https://app.dicloak.com/gin/v1/api/request/member/member_001' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "name": "Alice Updated",  "authority": "MEMBER",  "status": "ENABLED",  "member_group_id": "member_group_001",  "all_profile_groups": false,  "profile_group_ids": [    "profile_group_001"  ],  "manager_id": null,  "remark": "Replaced by API"}'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.id	string	成员 ID。
data.name	string	成员显示名称。
data.account	string	INTERNAL 为登录账号；EXTERNAL 为个人邮箱。
data.type	string	INTERNAL / EXTERNAL。
data.status	string	ENABLED / DISABLED；包含到期状态，固定到期时间已过视为 DISABLED。
data.authority	string	SUPER_ADMIN（超级管理员）/ ADMIN（管理员）/ MANAGER（经理）/ MEMBER（普通成员，英文 UI 为 Staff）。
data.member_group_id	string/null	功能权限成员分组 ID，不是成员身份。
data.member_group_name	string/null	成员分组名称。
data.manager	object/null	上级经理；未分配时为 null。
data.manager.id	string	经理成员 ID。
data.manager.name	string	经理显示名称。
data.all_profile_groups	boolean	是否拥有全部 Profile 分组访问权。
data.profile_group_list	array	指定授权的 Profile 分组；all_profile_groups=true 时返回 []。
data.profile_group_list[].id	string	Profile 分组 ID，不是单个 Profile ID。
data.profile_group_list[].name	string	Profile 分组名称。
data.remark	string/null	备注，空备注返回 null。
data.create_time	string/null	创建时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.update_time	string/null	修改时间，yyyy-MM-dd HH:mm:ss；不带时区偏移，不应自行按 UTC 解释。
data.expiration	object	到期停用配置；关闭时仅包含 enabled=false。
data.expiration.enabled	boolean	是否启用到期停用。
data.expiration.time_zone	string	开启时返回，IANA 时区，如 America/New_York。
data.expiration.mode	string	开启时返回：INSTANT 固定到期；LOGIN_START 首次登录后计时。
data.expiration.expires_at	string	仅 INSTANT 返回；time_zone 当地时间，格式 yyyy-MM-dd HH:mm。
data.expiration.days	integer	仅 LOGIN_START 返回；首次登录后有效天数。

成功响应示例

{  "code": 0,  "msg": "success",  "data": {    "id": "member_001",    "name": "Alice Updated",    "account": "alice001",    "type": "INTERNAL",    "status": "ENABLED",    "authority": "MEMBER",    "member_group_id": "member_group_001",    "member_group_name": "Customer Operations",    "manager": null,    "all_profile_groups": false,    "profile_group_list": [      {        "id": "profile_group_001",        "name": "Customer Profiles"      }    ],    "expiration": {      "enabled": true,      "time_zone": "America/New_York",      "mode": "INSTANT",      "expires_at": "2099-12-31 23:59"    },    "remark": "Replaced by API",    "create_time": "2026-09-24 10:00:00",    "update_time": "2026-09-24 11:00:00"  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	缺少必填字段、不合法的 null 或权限配置冲突。
400017	字段长度等格式错误。
300001	成员、分组或经理不在当前团队。
400011	成员分组停用或不可分配。
300108	名称重复。
300205	未续期的过期成员不能直接恢复。
300206	不允许修改或分配超级管理员。
300099	请求暂时无法处理，请稍后重试。
500000	请求处理失败。

错误响应示例：

{  "code": 400009,  "msg": "[profile_group_ids] is required",  "data": null,  "next": null}

9. 查询到期停用配置

查询指定成员是否启用到期停用，以及当前固定到期时间或首次登录有效天数。支持内部和外部成员。

请求地址

GET https://app.dicloak.com/gin/v1/api/request/member/{id}/expiration

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

路径参数

参数	类型	必填	说明
id	string	是	当前团队成员 ID；支持 INTERNAL、EXTERNAL。

Query 参数：无。

请求体

无。

请求示例

curl --request GET 'https://app.dicloak.com/gin/v1/api/request/member/member_001/expiration' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.enabled	boolean	是否启用到期停用。
data.time_zone	string	开启时返回，IANA 时区，如 America/New_York。
data.mode	string	开启时返回：INSTANT 固定到期；LOGIN_START 首次登录后计时。
data.expires_at	string	仅 INSTANT 返回；time_zone 当地时间，格式 yyyy-MM-dd HH:mm。
data.days	integer	仅 LOGIN_START 返回；首次登录后有效天数。

成功响应示例：关闭到期停用

{  "code": 0,  "msg": "success",  "data": {    "enabled": false  },  "next": null}

成功响应示例：固定时间到期

{  "code": 0,  "msg": "success",  "data": {    "enabled": true,    "time_zone": "America/New_York",    "mode": "INSTANT",    "expires_at": "2099-12-31 23:59"  },  "next": null}

成功响应示例：首次登录后计时

{  "code": 0,  "msg": "success",  "data": {    "enabled": true,    "time_zone": "America/New_York",    "mode": "LOGIN_START",    "days": 30  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
300001	成员不存在、已删除或不属于当前团队。
500000	请求处理失败。

错误响应示例：

{  "code": 300001,  "msg": "id does not identify an existing member in the current team",  "data": null,  "next": null}

10. 修改到期停用配置

开启、续期、切换或关闭成员到期停用规则。支持内部和外部成员，不允许修改超级管理员。

请求地址

PATCH https://app.dicloak.com/gin/v1/api/request/member/{id}/expiration

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。
Content-Type	string	是	固定为 application/json。

路径参数

参数	类型	必填	说明
id	string	是	当前团队成员 ID；支持 INTERNAL、EXTERNAL，不允许修改 SUPER_ADMIN。

Query 参数：无。

JSON Body 参数

至少提交一个字段，不接受 null。已开启时省略字段保持原值；切换模式须提供对应必填参数。

参数	类型	必填	说明
enabled	boolean	条件必填	从关闭变为开启必须传 true；传 false 时只能提交此字段。
time_zone	string	开启时必填	IANA 时区，如 America/New_York、Europe/London、Asia/Shanghai。
mode	string	开启时必填	INSTANT：指定时间停用；LOGIN_START：首次登录后计时。
expires_at	string	INSTANT 开启或切换时必填	当地时间，精确到分钟；格式 yyyy-MM-dd HH:mm，也接受 yyyy-MM-dd HH:mm:ss（忽略秒）。必须为未来时间，不可同时传 days。
days	integer	LOGIN_START 开启或切换时必填	1～36500，仅可在首次激活前设置，不可同时传 expires_at；续期使用 expires_at。

请求示例：开启固定日期到期

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/expiration' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "enabled": true,  "time_zone": "America/New_York",  "mode": "INSTANT",  "expires_at": "2099-12-31 23:59"}'

请求示例：开启首次登录后 30 天到期

此示例仅适用于尚未激活的成员。

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/expiration' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "enabled": true,  "time_zone": "America/New_York",  "mode": "LOGIN_START",  "days": 30}'

请求示例：固定日期续期

此示例要求当前已开启 INSTANT 到期规则。

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/expiration' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "expires_at": "2099-12-31 23:59"}'

请求示例：关闭到期停用

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/expiration' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "enabled": false}'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.enabled	boolean	是否启用到期停用。
data.time_zone	string	开启时返回，IANA 时区，如 America/New_York。
data.mode	string	开启时返回：INSTANT 固定到期；LOGIN_START 首次登录后计时。
data.expires_at	string	仅 INSTANT 返回；time_zone 当地时间，格式 yyyy-MM-dd HH:mm。
data.days	integer	仅 LOGIN_START 返回；首次登录后有效天数。

成功响应示例：固定日期到期

{  "code": 0,  "msg": "success",  "data": {    "enabled": true,    "time_zone": "America/New_York",    "mode": "INSTANT",    "expires_at": "2099-12-31 23:59"  },  "next": null}

成功响应示例：首次登录后计时

{  "code": 0,  "msg": "success",  "data": {    "enabled": true,    "time_zone": "America/New_York",    "mode": "LOGIN_START",    "days": 30  },  "next": null}

成功响应示例：关闭到期停用

{  "code": 0,  "msg": "success",  "data": {    "enabled": false  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	空请求、null、未开启时只提供部分配置、关闭时附加其他字段。
400017	mode 不是 INSTANT 或 LOGIN_START。
300001	成员不存在或不属于当前团队。
300204	time_zone 不是有效时区。
300205	到期时间、天数或续期参数不符合要求。
300206	不允许修改超级管理员。
300099	请求暂时无法处理，请稍后重试。
500000	请求处理失败。

错误响应示例：

{  "code": 300205,  "msg": "expires_at must be later than the current time",  "data": null,  "next": null}

11. 删除成员

删除内部成员时，同时删除其内部账号并退出已登录设备；删除外部成员时，仅移除其与当前团队的关联，保留个人账号及其他团队关系。

请求地址

DELETE https://app.dicloak.com/gin/v1/api/request/member/{id}

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

路径参数

参数	类型	必填	说明
id	string	是	当前团队成员 ID；支持 INTERNAL、EXTERNAL，不允许修改 SUPER_ADMIN。

Query 参数：无。

请求体

无，不需要提交 JSON。

请求示例

curl --request DELETE 'https://app.dicloak.com/gin/v1/api/request/member/member_001' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	null	成功后无业务数据，值为 null。
next	null	本接口不使用此字段。

成功响应示例

{  "code": 0,  "msg": "success",  "data": null,  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
300001	成员不存在、已删除或不属于当前团队。
300206	不允许删除超级管理员。
300099	请求暂时无法处理，请稍后重试。
500000	请求处理失败。

错误响应示例：

{  "code": 300206,  "msg": "id identifies the Super Admin (team owner); this member cannot be modified by this API",  "data": null,  "next": null}

12. 重置内部成员密码

重置内部成员密码，无需旧密码。成功后成员需重新登录。

请求地址

PATCH https://app.dicloak.com/gin/v1/api/request/member/{id}/password

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。
Content-Type	string	是	固定为 application/json。

路径参数

参数	类型	必填	说明
id	string	是	当前团队的 INTERNAL 成员 ID；不支持 EXTERNAL、SUPER_ADMIN。

Query 参数：无。

JSON Body 参数

参数	类型	必填	说明
password	string	是	8～25 字符；至少包含一个英文字母和一个数字；不能包含首尾空白。通过 HTTPS 提交原始密码字符串，请勿预先进行哈希、编码或加密转换。

请求示例

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/password' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "password": "NewExamplePass2026!"}'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	null	成功后无业务数据，值为 null。
next	null	本接口不使用此字段。

成功响应示例

{  "code": 0,  "msg": "success",  "data": null,  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	password 缺失、空白、字段类型错误。
300203	密码长度、字母数字组合或首尾空白不符合规则。
300001	成员不存在或不属于当前团队。
300207	目标为 EXTERNAL，不允许重置个人密码。
300206	不允许修改超级管理员。
500000	请求处理失败。

错误响应示例：

{  "code": 300203,  "msg": "password must be 8-25 characters, contain an English letter and a digit, and have no leading or trailing spaces",  "data": null,  "next": null}

13. 查询成员功能权限

查询路径 id 对应成员的功能权限，支持内部和外部成员。

请求地址

GET https://app.dicloak.com/gin/v1/api/request/member/{id}/permissions

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

路径参数

参数	类型	必填	说明
id	string	是	当前团队成员 ID；支持 INTERNAL、EXTERNAL。

Query 参数：无。

请求体

无。

请求示例

curl --request GET 'https://app.dicloak.com/gin/v1/api/request/member/member_001/permissions' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为列表对象，失败时可为 null。
data.list	array	本次返回的数据。
data.total	integer	符合条件的总数量。
data.summary	null	本接口不使用汇总字段。
data.page_token	null	本接口不使用游标分页。
data.list[].code	string	功能权限编码，以实际返回为准。
data.list[].name	string	功能权限名称。

成功响应示例

以下权限编码和名称使用占位值，接入时读取真实返回值。

{  "code": 0,  "msg": "success",  "data": {    "list": [      {        "code": "<PERMISSION_CODE>",        "name": "<PERMISSION_NAME>"      }    ],    "total": 1,    "summary": null,    "page_token": null  }}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
300001	目标成员不存在、已删除或不属于当前团队。
500000	请求处理失败。

错误响应示例：

{  "code": 300001,  "msg": "id does not identify an existing member in the current team",  "data": null}

14. 查询内部成员登录验证

读取内部成员当前邮箱验证、2FA 开关及触发条件。2FA 开启时会返回当前密钥，请按敏感信息处理。

请求地址

GET https://app.dicloak.com/gin/v1/api/request/member/{id}/login-verification

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

路径参数

参数	类型	必填	说明
id	string	是	当前团队的 INTERNAL 成员 ID；不支持 EXTERNAL、SUPER_ADMIN。

Query 参数：无。

请求体

无。

请求示例

curl --request GET 'https://app.dicloak.com/gin/v1/api/request/member/member_001/login-verification' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.check_email	boolean	是否开启邮箱验证。
data.email	string	仅 check_email=true 时返回验证码接收邮箱。
data.check_2fa	boolean	是否开启 2FA。
data.secret_2fa	string	仅 check_2fa=true 时返回；这是验证器密钥，不是动态验证码。
data.trigger	object	当前验证触发配置。
data.trigger.mode	string	EVERY_LOGIN / DEVICE_OR_INTERVAL。
data.trigger.interval	integer	仅 DEVICE_OR_INTERVAL 返回；间隔 1～168。
data.trigger.unit	string	仅 DEVICE_OR_INTERVAL 返回；HOUR / DAY。
data.trigger.logout_on_timeout	boolean	仅 DEVICE_OR_INTERVAL 返回；达到间隔后是否自动退出。

响应头：Cache-Control: no-store。

成功响应示例：未开启验证

{  "code": 0,  "msg": "success",  "data": {    "check_email": false,    "check_2fa": false,    "trigger": {      "mode": "EVERY_LOGIN"    }  },  "next": null}

成功响应示例：邮箱验证与 2FA 均开启

{  "code": 0,  "msg": "success",  "data": {    "check_email": true,    "email": "alice.verify@example.com",    "check_2fa": true,    "secret_2fa": "<CURRENT_2FA_SECRET>",    "trigger": {      "mode": "DEVICE_OR_INTERVAL",      "interval": 7,      "unit": "DAY",      "logout_on_timeout": false    }  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
300001	成员不存在、已删除或不属于当前团队。
300162	EXTERNAL 不支持此登录验证接口。
300206	不允许通过此接口访问超级管理员安全配置。
500000	请求处理失败。

错误响应示例：

{  "code": 300162,  "msg": "id must identify an INTERNAL member; login verification is not editable for EXTERNAL members",  "data": null,  "next": null}

15. 修改内部成员登录验证

修改验证邮箱、邮箱验证开关、2FA 开关及触发条件。顶层未提交字段保持当前值；trigger 提交后作为完整对象替换。

请求地址

PATCH https://app.dicloak.com/gin/v1/api/request/member/{id}/login-verification

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。
Content-Type	string	是	固定为 application/json。

路径参数

参数	类型	必填	说明
id	string	是	当前团队的 INTERNAL 成员 ID；不支持 EXTERNAL、SUPER_ADMIN。

Query 参数：无。

JSON Body 参数

至少提交 email、check_email、check_2fa、trigger 中的一项。空对象会被拒绝。

参数	类型	必填	说明
check_email	boolean	否	省略保持；开启时须配置有效 email，不接受 null。
email	string/null	否	验证码接收邮箱，不是登录账号；允许更新且无需验证码。邮箱验证开启时不能清空。
check_2fa	boolean	否	true 开启 2FA，false 关闭；省略保持，不接受 null。密钥通过响应 secret_2fa 获取，不允许在请求中提交。
trigger	object	否	省略保持当前值；提交时整体替换触发配置，不能为 null。
trigger.mode	string	提交 trigger 时必填	EVERY_LOGIN：每次登录团队验证；DEVICE_OR_INTERVAL：换设备或达到时间间隔后验证。
trigger.interval	integer	间隔模式必填	1～168。EVERY_LOGIN 不允许提交。
trigger.unit	string	间隔模式必填	HOUR / DAY。EVERY_LOGIN 不允许提交。
trigger.logout_on_timeout	boolean	否	间隔模式省略时为 false；true 表示到时自动退出。EVERY_LOGIN 不允许提交，不能为 null。

请求示例：开启邮箱验证

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/login-verification' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "check_email": true,  "email": "alice.verify@example.com",  "trigger": {    "mode": "EVERY_LOGIN"  }}'

请求示例：开启 2FA 并设置间隔验证

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/login-verification' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "check_2fa": true,  "trigger": {    "mode": "DEVICE_OR_INTERVAL",    "interval": 7,    "unit": "DAY",    "logout_on_timeout": false  }}'

请求示例：仅更新验证邮箱

仅修改验证码接收邮箱，check_email 和登录账号 account 不变。

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/login-verification' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "email": "new.verify@example.com"}'

请求示例：关闭邮箱验证并清空验证邮箱

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/login-verification' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "check_email": false,  "email": null}'

请求示例：关闭全部登录验证

curl --request PATCH 'https://app.dicloak.com/gin/v1/api/request/member/member_001/login-verification' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>' \  --header 'Content-Type: application/json' \  --data-raw '{  "check_email": false,  "check_2fa": false}'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.check_email	boolean	是否开启邮箱验证。
data.email	string	仅 check_email=true 时返回验证码接收邮箱。
data.check_2fa	boolean	是否开启 2FA。
data.secret_2fa	string	仅 check_2fa=true 时返回；这是验证器密钥，不是动态验证码。
data.trigger	object	当前验证触发配置。
data.trigger.mode	string	EVERY_LOGIN / DEVICE_OR_INTERVAL。
data.trigger.interval	integer	仅 DEVICE_OR_INTERVAL 返回；间隔 1～168。
data.trigger.unit	string	仅 DEVICE_OR_INTERVAL 返回；HOUR / DAY。
data.trigger.logout_on_timeout	boolean	仅 DEVICE_OR_INTERVAL 返回；达到间隔后是否自动退出。

响应头：Cache-Control: no-store。返回更新后的完整登录验证配置。

成功响应示例：开启邮箱验证

假设请求前未启用 2FA，响应如下。

{  "code": 0,  "msg": "success",  "data": {    "check_email": true,    "email": "alice.verify@example.com",    "check_2fa": false,    "trigger": {      "mode": "EVERY_LOGIN"    }  },  "next": null}

成功响应示例：开启 2FA 并设置间隔验证

假设请求前已开启邮箱验证，响应如下。

{  "code": 0,  "msg": "success",  "data": {    "check_email": true,    "email": "alice.verify@example.com",    "check_2fa": true,    "secret_2fa": "<CURRENT_2FA_SECRET>",    "trigger": {      "mode": "DEVICE_OR_INTERVAL",      "interval": 7,      "unit": "DAY",      "logout_on_timeout": false    }  },  "next": null}

成功响应示例：关闭全部验证

假设原触发配置为每次登录验证，关闭开关后保留该配置。

{  "code": 0,  "msg": "success",  "data": {    "check_email": false,    "check_2fa": false,    "trigger": {      "mode": "EVERY_LOGIN"    }  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
400009	空请求、不合法的 null、trigger 模式或间隔字段错误。
400017	开启邮箱验证但邮箱无效。
300001	成员不存在或不属于当前团队。
300162	外部成员不支持登录验证管理。
300206	不允许修改超级管理员。
300099	请求暂时无法处理，请稍后重试。
500000	请求处理失败。

错误响应示例：

{  "code": 400009,  "msg": "trigger.mode is required",  "data": null,  "next": null}

16. 生成并启用新的 2FA 密钥

每次成功调用均返回新的 2FA 密钥并立即启用，旧密钥失效，无需确认。

请求地址

POST https://app.dicloak.com/gin/v1/api/request/member/{id}/totp

请求头

参数	类型	必填	说明
X-HTTP-KEY	string	是	当前团队的 HTTP API Key。

路径参数

参数	类型	必填	说明
id	string	是	当前团队的 INTERNAL 成员 ID；不支持 EXTERNAL、SUPER_ADMIN。

Query 参数：无。

请求体

无。不提交旧密钥、新密钥或验证码。

请求示例

curl --request POST 'https://app.dicloak.com/gin/v1/api/request/member/member_001/totp' \  --header 'X-HTTP-KEY: <YOUR_TEAM_HTTP_API_KEY>'

响应参数

字段	类型	说明
code	integer	0 表示成功；非 0 表示业务失败。
msg	string	结果说明。
data	object/null	成功时为业务对象，失败时可为 null。
next	null	本接口不使用此字段。
data.check_2fa	boolean	成功时为 true，表示新密钥已经启用。
data.secret_2fa	string	新的 2FA 验证器密钥，立即生效。

响应头：Cache-Control: no-store。

成功响应示例

{  "code": 0,  "msg": "success",  "data": {    "check_2fa": true,    "secret_2fa": "<NEW_SERVER_GENERATED_2FA_SECRET>"  },  "next": null}

常见错误

code	原因
400003	X-HTTP-KEY 缺失或无效。
300001	成员不存在或不属于当前团队。
300162	外部成员不支持 2FA 管理。
300206	不允许修改超级管理员。
400017	已有启用的邮箱验证配置中邮箱无效。
400009	无法生成新的 2FA 密钥。
300099	请求暂时无法处理，请稍后重试。
500000	请求处理失败。

错误响应示例：

{  "code": 300162,  "msg": "id must identify an INTERNAL member; login verification is not editable for EXTERNAL members",  "data": null,  "next": null}