Skip to main content

查询可信设备接口

分页查询企业内已登记的设备，支持按关键词、可信状态 trusted 以及 created_from 和 created_to 时间区间过滤。

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

请求参数

名称位置类型必填说明
keywordquerystringFalse搜索关键词
trustedquerystringFalse是否可信
created_fromquerystringFalse创建时间起点
created_toquerystringFalse创建时间终点

请求示例

curl --request GET 'https://example.invalid/api/openapi/v1/trusted-devices' \
  --header 'Authorization: Bearer <API_KEY>'

响应字段

名称类型说明
itemsarray结果列表
items[].created_atstring创建时间
items[].created_bystring创建主体标识
items[].created_by_emailstring创建主体邮箱
items[].created_by_namestring创建主体名称
items[].device_namestring设备名称
items[].idstring记录标识
items[].login_usernamestring设备登录用户名
items[].mac_addressstring设备 MAC 标识
items[].modelstring设备型号
items[].operating_systemstring操作系统
items[].serial_numberstring设备序列号 SN
items[].sourcestring设备登记来源；enum=['single', 'import', 'first_device_auto_trust', 'approval']
items[].trustedboolean是否可信
items[].updated_atstring更新时间
items[].updated_bystring更新主体标识
items[].updated_by_emailstring更新主体邮箱
items[].updated_by_namestring更新主体名称
items[].userobject设备所属用户快照
items[].user.department_idstring部门标识
items[].user.department_namestring部门名称
items[].user.department_pathstring部门路径
items[].user.departmentsarray用户部门快照
items[].user.departments[].idstring记录标识
items[].user.departments[].namestring名称
items[].user.departments[].pathstringpath
items[].user.emailstring用户邮箱
items[].user.employee_nostring员工编号
items[].user.org_idstring所属组织标识
items[].user.user_idstring设备所属用户标识
items[].user.user_namestring用户姓名
items[].versioninteger并发控制版本
pageinteger页码，从 1 开始
page_sizeinteger每页条数，最多 100
totalinteger总记录数

错误处理

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

接口语义与安全边界

返回包含用户姓名、邮箱、工号、部门、SN/MAC、设备登录用户名及操作主体信息。读取 Scope 即授权读取这些组织内信息；未传 trusted 时可包含可信和不可信设备。