创建可信设备接口

Scope: admin.v1.trusted-devices.manage
权限项: 可信设备管理
权限类型: manage
接口: POST/api/openapi/v1/trusted-devices

使用 Authorization: Bearer <API_KEY>。应用必须配置“全部用户”范围（subject_scope={"mode":"all"}）；受限或无效范围在业务执行前返回 403 openapi_subject_scope_denied。各 Scope 独立授权，互不隐含。组织及应用操作主体取自可信鉴权，不接受请求参数指定。

请求参数

名称	位置	类型	必填	说明
`Idempotency-Key`	header	`string`	True	幂等键，创建和导入必填
`device_name`	body	`string`	True	设备名称；maxLength=255
`login_username`	body	`string`	False	设备登录用户名；maxLength=255
`mac_address`	body	`string`	False	设备 MAC 标识；maxLength=32
`model`	body	`string`	False	设备型号；maxLength=255
`operating_system`	body	`string`	False	操作系统；maxLength=128
`serial_number`	body	`string`	False	设备序列号 SN；maxLength=255
`trusted`	body	`boolean`	True	是否可信
`user_id`	body	`string`	True	设备所属用户标识

请求示例

curl --request POST 'https://example.invalid/api/openapi/v1/trusted-devices' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: device-operation-001' \
  --header 'Content-Type: application/json' \
  --data '{"device_name": "example", "serial_number": "example", "trusted": true, "user_id": "11111111-1111-4111-8111-111111111111"}'

响应字段

名称	类型	说明
`created_at`	`string`	创建时间
`created_by`	`string`	创建主体标识
`created_by_email`	`string`	创建主体邮箱
`created_by_name`	`string`	创建主体名称
`device_name`	`string`	设备名称
`id`	`string`	记录标识
`login_username`	`string`	设备登录用户名
`mac_address`	`string`	设备 MAC 标识
`model`	`string`	设备型号
`operating_system`	`string`	操作系统
`serial_number`	`string`	设备序列号 SN
`source`	`string`	设备登记来源；enum=['single', 'import', 'first_device_auto_trust', 'approval']
`trusted`	`boolean`	是否可信
`updated_at`	`string`	更新时间
`updated_by`	`string`	更新主体标识
`updated_by_email`	`string`	更新主体邮箱
`updated_by_name`	`string`	更新主体名称
`user`	`object`	设备所属用户快照
`user.department_id`	`string`	部门标识
`user.department_name`	`string`	部门名称
`user.department_path`	`string`	部门路径
`user.departments`	`array`	用户部门快照
`user.departments[].id`	`string`	记录标识
`user.departments[].name`	`string`	名称
`user.departments[].path`	`string`	path
`user.email`	`string`	用户邮箱
`user.employee_no`	`string`	员工编号
`user.org_id`	`string`	所属组织标识
`user.user_id`	`string`	设备所属用户标识
`user.user_name`	`string`	用户姓名
`version`	`integer`	并发控制版本

错误处理

沿用 {error, detail, code} 错误结构。身份校验失败为 401/403；缺少 Scope 或非全部用户范围为 403；资源不存在为 404；冲突或旧版本为 409；参数不合法为 400/422；依赖不可用为 503。业务错误沿用控制台语义。

接口语义与安全边界

这是管理员直接登记能力，可以直接创建可信设备，不要求先提交申请。至少填写 SN 或 MAC；遵守原有用户有效性与标识冲突校验。

​请求参数

​请求示例

​响应字段

​错误处理

​接口语义与安全边界

请求参数

请求示例

响应字段

错误处理

接口语义与安全边界