菜单

API文档

下载
文档属性 内容
文档名称 DKEY AM API 标准文档
接口数量 43
适用系统 DKEY AM
编码 UTF-8

本文档用于 DKEY AM 系统接口对接。示例中的账号、密码、密钥、手机号、邮箱、IP 地址及标识符

仅用于说明，接入方必须替换为当前环境的有效值，且不得使用生产凭据。

目录

  1. 文档说明

  2. 接入约定

  3. API 目录

  4. 接口定义

  5. 数据结构

  6. 统一错误码说明

  7. 附录 A：目录说明

  8. 附录 B：安全说明

1. 文档说明

1.1 目的

本文档用于指导 DKEY AM 的认证、日志、会话、用户、组织、角色、令牌、站点、终端及 MAC 管理接口对接。

1.2 范围

  • 共包含 43 个接口，按认证与日志、用户、组织、角色、令牌及系统管理分类。

  • 接口路径主要位于 /am/webauth/1/**、/am/rest/p/1/**、/am/rest/p/2/** 与 /am/api/admin/**。

  • 不包含部署、租户初始化、数据库配置以及页面端操作说明。

1.3 环境地址

协议 默认端口 Base URL 示例
HTTP 8080 http://{host}:8080
HTTPS 8443 https://{host}:8443

生产环境应使用 HTTPS。文档中的 {baseUrl} 表示实际部署环境的服务地址。

2. 接入约定

2.1 请求格式

  • HTTP端口8080，HTTPS端口8443

  • 所有参数的值使用url编码，格式utf-8，编码前：中文，编码后：%e4%b8%ad%e6%96%87

  • GET请求地址拼接示例（以1.1接口为例）http://认证系统地址:8080/am/webauth/1/strong/authenticate?参数名=参数值\&参数名=参数值\.\.\.\.\.\.

  • POSTapplication/x\-www\-form\-urlencoded

  • URL 参数使用 UTF-8 编码。

  • JSON 请求应携带 Content-Type: application/json; charset=UTF-8。

  • 表单请求使用 application/x-www-form-urlencoded；以具体接口定义为准。

  • 时间字段无特别说明时为 Unix 毫秒时间戳。

  • 布尔值使用 JSON 的 true / false，不得用字符串代替。

2.2 认证方式

接口族 认证方式 说明
/am/webauth/1/** 共享密钥 请求参数通常包含 tenantName、accessServerName、sharedSecret
/am/rest/p/1/**、/am/rest/p/2/** 管理员参数 通常包含 adminLoginName、adminPassword、tenantName
/am/api/admin/** Basic Auth Authorization: Basic <base64username:password>
第三方回调 自定义密钥 URL 与认证字段由第三方实现和系统配置决定

2.3 通用响应

success=true 且 errorCode=0 表示成功；success=true 但错误码非 0 表示部分失败；

success=false 表示失败。部分接口还返回 requestId、errorId 与 data。

3. API 目录

下表按业务域归类，共 41 个接口。

序号 业务域 方法 路径 说明
1 认证、日志与会话 GET/POST /am/webauth/1/strong/authenticate 用户认证
2 认证、日志与会话 GET/POST /am/webauth/1/strong/passwordRequirement 用户认证策略
3 认证、日志与会话 GET/POST /am/webauth/1/strong/getDynamicPassword 发送动态密码
4 认证、日志与会话 GET /am/api/admin/tenant/tacacs/report/auth/search TACACS+ 认证日志
5 认证、日志与会话 GET /am/api/admin/tenant/tacacs/report/audit/search TACACS+ 审计日志
6 认证、日志与会话 GET /am/api/admin/stat/session/list 登录会话列表
7 用户 GET/POST /am/rest/p/1/identity/user/infos 拉取所有用户信息
8 用户 GET/POST /am/rest/p/1/identity/user/unbindUserTerminals 解绑用户终端
9 用户 GET/POST /am/rest/p/1/identity/user/bindUserTerminals 绑定用户终端
10 用户 GET/POST /am/rest/p/1/identity/user/applyTemporaryUser 申请临时用户
11 用户 POST /am/api/admin/tenant/identity/user/delete 管理端删除用户
12 用户 POST /am/rest/p/2/identity/user/incSync 增量同步用户 V2
13 用户 POST /am/rest/p/2/identity/user/add 添加用户
14 用户 POST /am/rest/p/2/identity/user/update 更新用户
15 组织 POST /am/api/admin/tenant/identity/group/add 新增组织
16 组织 GET /am/api/admin/tenant/identity/group/list 获取全部组织
17 组织 POST /am/api/admin/tenant/identity/group/update 更新组织
18 角色 GET /am/api/admin/tenant/identity/role/list 获取站点角色
19 角色 POST /am/api/admin/tenant/identity/role/add 创建角色
20 角色 POST /am/api/admin/tenant/identity/role/update 更新角色
21 令牌 GET/POST /am/rest/p/1/token/binding/list 用户和令牌的绑定关系
22 令牌 GET/POST /am/rest/p/1/token/mobileToken/deliver 派发手机令牌
23 令牌 GET/POST /am/rest/p/1/token/mobileToken/userQrCode 获取手机令牌二维码
24 令牌 GET/POST /am/rest/p/1/token/mobileToken/bindAndWriteMobileTokenQrCode 绑定并获取二维码
25 令牌 GET/POST /am/rest/p/1/token/mobileToken/completeMobileTokenBinding 完成手机令牌绑定
26 令牌 GET/POST /am/rest/p/1/token/bind 绑定时间型令牌
27 令牌 GET/POST /am/rest/p/1/token/unbind 解绑时间型令牌
28 令牌 GET/POST /am/rest/p/1/token/unbindAll 解绑所有时间型令牌
29 令牌 GET/POST /am/rest/p/1/token/mobileToken/data 获取手机令牌信息
30 系统、终端与 MAC GET/POST /am/rest/p/1/tenant/list 站点列表
31 系统、终端与 MAC GET/POST /am/rest/p/1/identity/blackWhiteMacAddressList/add 新增 MAC 黑白名单
32 系统、终端与 MAC POST /am/rest/p/1/identity/blackWhiteMacAddressList/list/replace 替换Mac地址黑白名单
33 系统、终端与 MAC GET /am/api/admin/tenant/identity/macList/list MAC 列表集
34 系统、终端与 MAC GET /am/api/admin/tenant/identity/macList/macItem/list 终端 MAC 地址列表
35 系统、终端与 MAC POST /am/api/admin/tenant/identity/macList/add 新增列表集
36 系统、终端与 MAC POST /am/api/admin/tenant/identity/macList/update 编辑列表集
37 系统、终端与 MAC POST /am/api/admin/tenant/identity/macList/delete 删除列表集
38 系统、终端与 MAC POST /am/api/admin/tenant/identity/macList/macItem/add 新增终端
39 系统、终端与 MAC POST /am/api/admin/tenant/identity/macList/macItem/update 编辑终端
40 系统、终端与 MAC POST /am/api/admin/tenant/identity/macList/macItem/delete 删除终端
41 系统、终端与 MAC GET /am/api/admin/tenant/identity/macList/macItem/search 查询 MAC 列表项
42 用户 GET /am/api/admin/tenant/identity/user/password/expireTime 获取用户密码到期时间
43 用户 GET /am/rest/p/1/identity/user/resetPassword 用户改密

4. 接口定义

本章给出全部接口的请求方式、参数、示例和响应。同时允许 GET/POST 的接口，生产接入应优先采用

不会把敏感请求体写入 URL 的方式。

4.1 认证、日志与会话

4.1.1 认证

请求： GET /am/webauth/1/strong/authenticate 或 POST /am/webauth/1/strong/authenticate

请求参数 必填 说明
tenantName 是 站点名称
accessServerName 是 认证设备名称
需要在认证系统上创建认证设备，设备类型为：API调用
sharedSecret 是 认证设备共享秘钥
loginName 是 用户登录名
password 是 密码，多种情况【不要加号】：
（1）用户静态密码
（2）令牌动态密码
（3）用户静态密码+令牌动态密码
terminalIp 否 用户终端ip
terminalMac 否 用户终端MAC
响应示例
JSON
{
"success": true,
"errorCode": 0,
"dynamicPasswordLength": 6,
"message": null,
"roles":
"admin",
"dev"

}
响应参数 说明
roles 用户角色

4.1.2 用户认证策略

请求： GET /am/webauth/1/strong/passwordRequirement 或 POST /am/webauth/1/strong/passwordRequirement

请求参数 必填 说明
tenantName 是 站点名称
accessServerName 是 认证设备名称
需要在认证系统上创建认证设备，设备类型为：API调用
sharedSecret 是 认证设备共享秘钥
loginName 是 用户登录名
terminalIp 否 用户终端ip
terminalMac 否 用户终端MAC
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": {
"staticPasswordRequired": false,
"dynamicPasswordRequired": true,
"needsGetDynamicPassword": false,
"dynamicPasswordEnforced": true
},
"message": null
}
响应参数 说明
staticPasswordRequired 是否需要静态密码
dynamicPasswordRequired 是否需要动态密码
如果策略为不需要动态密码，值为false
如果策略为需要动态密码，用户有令牌，值为true
如果策略为需要动态密码，用户没有令牌，值为false
needsGetDynamicPassword 是否能获取动态密码
如果为true，调用接口1.3，将发送动态密码给用户
dynamicPasswordEnforced 强制使用动态密码（可以通过动态密码策略策略：用户未使用动态密码，禁止或允许，来进行配置）
如果值为true，但是用户登录没有使用令牌，则登录被禁止

4.1.3 发送动态密码

请求： GET /am/webauth/1/strong/getDynamicPassword 或 POST /am/webauth/1/strong/getDynamicPassword

请求参数 必填 说明
tenantName 是 站点名称
accessServerName 是 认证设备名称
需要在认证系统上创建认证设备，设备类型为：API调用
sharedSecret 是 认证设备共享秘钥
loginName 是 用户登录名
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": null,
"message": null
}

4.1.4 获取 TACACS+ 认证日志列表

HTTP
GET {baseUrl}/am/api/admin/tenant/tacacs/report/auth/search

认证：继承管理端认证，即 Basic Auth。

Query 参数 类型 必填 说明
tenantId string 是 站点 ID
loginName string 否 登录名
terminalIp string 否 终端 IP
accessServerIp string 否 设备 IP
accessServerName string 否 设备名称
command string 否 命令
privilegeLevel arraystring 否 权限级别，可重复传参
result integer 否 结果：1 成功，0 失败
startTime integerint64 是 查询开始时间，Unix 毫秒时间戳
endTime integerint64 是 查询结束时间，Unix 毫秒时间戳
firstResult integer 是 分页起始位置
maxResults integer 是 最大返回数量

成功响应：

JSON
{
"success": true,
"errorCode": 0,
"data":
\{
"id": "\",
"tenantId": "\",
"loginName": "zhangsan",
"terminalIp": "127\.0\.0\.1",
"accessServerName": "rad",
"accessServerIp": "10\.0\.0\.1",
"accessServerId": "\",
"accessServerBrand": "通用设备",
"command": "display version",
"privilegeLevel": "1",
"result": 1,
"recordType": 1,
"createTime": 1784084235000,
"createTimeInMicroseconds": 1784084235195874
\}
,
"message": null
}

4.1.5 获取 TACACS+ 审计日志列表

HTTP
GET {baseUrl}/am/api/admin/tenant/tacacs/report/audit/search

认证与 Query 参数同“获取 TACACS+ 认证日志列表”。成功响应为通用结构，data 为审计日志数组；

接口定义仅给出空数组示例，未提供审计记录字段结构。

JSON
{
"success": true,
"errorCode": 0,
"data": \[\],
"message": null
}

4.1.6 获取登录会话列表

HTTP
GET {baseUrl}/am/api/admin/stat/session/list

认证：Basic Auth。指定 tenantId 时查询该站点并校验站点会话读取权限；不传 tenantId 时查询

全局会话，并校验部署级操作日志读取权限。

Query 参数 类型 必填 说明
tenantId string 否 站点 ID；为空时查询全局会话
tenantName string 否 站点名称，模糊匹配
identityStoreName string 否 用户源名称，模糊匹配
identityStoreIds arraystring 否 用户源 ID 列表；传入时使用数据库查询
userIdentity string 否 用户身份，模糊匹配
personalName string 否 用户姓名，模糊匹配
userLoginName string 否 用户登录名，模糊匹配
userLoginNameRaw string 否 原始登录名，模糊匹配
terminalIp string 否 终端 IPv4，模糊匹配
terminalIp6 string 否 终端 IPv6，模糊匹配
terminalMac string 否 终端 MAC 地址，模糊匹配
terminalPlatform arraystring 否 终端平台列表，如 Windows、Linux、Android
tunnelClientIp string 否 隧道客户端 IP，模糊匹配
accessServerName string 否 接入设备名称，模糊匹配
accessServerIp string 否 接入设备 IP，模糊匹配
serviceSet string 否 服务集（SSID 名称），模糊匹配
apGroupLocation string 否 AP 组位置，模糊匹配
apLocation string 否 AP 位置，模糊匹配
apMac string 否 AP MAC 地址，模糊匹配
type arrayinteger 否 会话类型：1 强认证、2 Portal、3 802.1X 随机账号、4 NDA 计算机认证、5 UC、6 NDA
state arrayinteger 否 会话状态列表
signonType arraystring 否 登录方式标识列表，如 userPassword、sms、qrCode、ndaSso
eap boolean 否 是否为 802.1X 会话
isPortalRevisitLogin boolean 否 是否 Portal 免认证
isBackgroundMacAuth boolean 否 是否后台 MAC 认证
isNewUser boolean 否 是否新用户
startTime integerint64 否 查询开始时间，Unix 毫秒时间戳；0 按未传处理
endTime integerint64 否 查询结束时间，Unix 毫秒时间戳；0 按未传处理
orderBy string 否 排序字段
order string 否 排序方向，如 asc、desc
firstResult integer 是 分页起始位置
maxResults integer 是 最大返回数量

数组参数通过重复同名 Query 参数传递，例如 type=1&type=2。

成功响应：

JSON
{
"success": true,
"errorCode": 0,
"data": {
"totalCount": 1,
"data":
\{
"sessionId": "\",
"type": 1,
"state": 200,
"tenantId": "\",
"tenantName": "示例站点",
"identityStoreId": "\",
"identityStoreName": "本地用户源",
"userId": "\",
"userLoginName": "zhangsan",
"terminalIp": "10\.0\.0\.10",
"terminalMac": "AA:BB:CC:DD:EE:FF",
"accessServerName": "接入设备",
"portalTypeUuid": "userPassword",
"portalType": "用户名密码",
"encodedTokens": "",
"cLoginTime": 1784084235000,
"cLastActiveTime": 1784084235000,
"messages": \[
}
]
},
"message": null
}

返回会话对象由 AccessSessionInfo.toJson\(\) 生成，并额外补充 identityStoreName、

encodedTokens；嵌套的 accessServer 对象会移除 sharedSecret。

4.2 用户

4.2.4 拉取所有用户的信息

请求： GET /am/rest/p/1/identity/user/infos 或 POST /am/rest/p/1/identity/user/infos

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
type 是 查找方式
all：所有
updateTime：用户更新时间
firstResult 是 返回的第一条数据，在数据库中的位置，int类型，最小值0
maxResult 是 返回的最大条数，int类型
startUpdateTime 用户更新时间，起始时间，时间戳毫秒
需要和endUpdateTime一起使用
endUpdateTime 用户更新时间，结束时间，时间戳毫秒
需要和startUpdateTime一起使用
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": {
"totalCount": 8,
"startRow": 0,
"data": \[\]
},
"message": null
}
响应参数 说明
totalCount 数据库中的数据总条数
startRow 和入参的firstResult相等
data 用户信息，UserInfo数组

4.2.5 解绑用户终端

请求： GET /am/rest/p/1/identity/user/unbindUserTerminals 或 POST /am/rest/p/1/identity/user/unbindUserTerminals

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
deleteFingerprint
 是否删除指纹库的MAC地址
默认值false：不删除
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": null,
"message": null
}

4.2.6 绑定用户终端

请求： GET /am/rest/p/1/identity/user/bindUserTerminals 或 POST /am/rest/p/1/identity/user/bindUserTerminals

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
unbindPrevious 是否解绑用户以前的终端
默认为true，绑定前先解绑以前的用户终端
macAddresses 是 绑定的MAC地址列表
示例："D0:25:98:35:C3:62", "10:45:F8:35:CC:E1"
响应示例
JSON
{
"requestId": null,
"success": true,
"errorCode": 0,
"errorId": null,
"data": null,
"message": null
}

4.2.7 申请临时用户

请求： GET /am/rest/p/1/identity/user/applyTemporaryUser 或 POST /am/rest/p/1/identity/user/applyTemporaryUser

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
默认本地用户源名：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
applierLoginName 是 申请人登录名，需要提前配置
sendAccountTo 是 1：发送到手机（临时用户手机）
2：发送到邮箱（临时用户邮箱）
mobile （sendAccountTo=1时，必填，作为登录账号）手机号
email （sendAccountTo=2时，必填，作为登录账号）邮箱
sendToApplier 发给申请人邮箱（默认false）
sendToTemporaryUser sendAccountTo=2时，发给临时用户邮箱（默认true）
startTime 是 有效期，起始时间，时间戳，毫秒
endTime 是 有效期，结束时间，时间戳，毫秒
roleName 角色（需要是认证系统中已经存在的角色）
personalName 姓名
number 证件号码（工号，护照等）
idCardNumber 身份证号码
company 公司
description 描述
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": \[\],
"message": null
}

4.2.8 删除用户（管理接口）

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/user/delete

认证：Basic Auth。

字段 类型 必填 说明
tenantId string 是 站点 ID
identityStoreId string 是 用户源 ID
parentGroupId string 否 用户当前所在组织 ID；用于组织级写权限校验
userId string 是 用户 ID
writeToExternal boolean 否 是否同步删除外部用户源中的用户，默认 false
forceDelete boolean 否 存在访客审批引用时是否强制删除，默认 false
JSON
{
"tenantId": "<tenant-id>",
"identityStoreId": "<identity-store-id>",
"parentGroupId": "<parent-group-id>",
"userId": "<user-id>",
"writeToExternal": false,
"forceDelete": false
}

成功响应为通用无 data 响应。存在访客审批引用且未强制删除时，返回 DELETE_CONFIRM \-5001。

4.2.9 增量同步用户 V2

HTTP
POST {baseUrl}/am/rest/p/2/identity/user/incSync

Query 参数：adminLoginName、adminPassword、tenantName，均为必填字符串。

请求体：

字段 类型 必填 说明
tenantName string 是 站点名称
identityStoreName string 是 用户源名称默认本地用户源名：06bc758e\-04f2\-40b3\-9d6c\-562b115aeb3c
updateRole boolean 否 是否同步角色，默认 true
useReverseSync boolean 否 是否通过匹配的 Hub 配置执行反向同步，默认 false
user UserInput 是 用户数据
JSON
{
"tenantName": "<tenant-name>",
"identityStoreName": "<identity-store-name>",
"updateRole": true,
"useReverseSync": false,
"user": {
"externalUserId": "<external-user-id>",
"loginName": "zhangsan",
"personalName": "张三",
"password": "<user-password>",
"mobiles": "\",
"roles": "研发人员",
"groupPath": "/研发部",
"enabled": true,
"customAttributes":
\{
"name": "entryUUID",
"value": "\",
"type": 1
\}

}
}

成功响应：通用响应结构，data 为同步后的用户对象。

4.2.10 添加用户

HTTP
POST {baseUrl}/am/rest/p/2/identity/user/add

Query 参数和请求体与“增量同步用户 V2”相同。成功响应的 data 为新增后的用户对象。

4.2.11 更新用户

HTTP
POST {baseUrl}/am/rest/p/2/identity/user/update

Query 参数：adminLoginName、adminPassword、tenantName，均为必填字符串。

请求体结构与“增量同步用户 V2”一致；更新时必须提供可定位用户的标识。updateRole 默认为 true，useReverseSync 默认为 false：

JSON
{
"tenantName": "<tenant-name>",
"identityStoreName": "<identity-store-name>",
"updateRole": false,
"useReverseSync": false,
"user": {
"userId": "<user-id>",
"externalUserId": "<external-user-id>",
"loginName": "zhangsan",
"personalName": "张三",
"enabled": true
}
}
updateRole 默认值为 true；useReverseSync=true 时必须存在站点名和用户源名均匹配的 Hub 配置。

成功响应的 data 为更新后的用户对象。

4.2.12 获取用户密码到期时间

请求： GET /am/api/admin/tenant/identity/user/password/expireTime

认证：Basic Auth。

字段 类型 必填 说明
tenantId string 是 站点ID
identityStoreId string 否 用户源ID
parentGroupId string 否 用户组ID
userId string 是 用户 ID

说明：用户组ID与用户源ID不能都不传，必须传其中之一

成功响应示例：

JSON
{
"success": true,
"errorCode": 0,
"data": 1678098781000,//密码过期时间
"message": null
}

失败响应示例：

JSON
{
"success": false,
"errorCode": -6,
"message": "Target cannot be null"
}

4.2.13 用户改密

请求： GET /am/rest/p/1/identity/user/resetPassword

认证：Basic Auth。

字段 类型 必填 说明
tenantName string 是 站点名
identityStoreName string 是 用户源名默认本地用户源名：06bc758e\-04f2\-40b3\-9d6c\-562b115aeb3c
loginName string 是 用户名
password string 是 密码
needPasswordPolicy boolean 否 是否使用密码复杂度策略，不传默认使用

成功响应示例：

JSON
{
"requestId": null,
"success": true,
"errorCode": 0,
"errorId": null,
"data": null,
"message": null
}

失败响应示例：

JSON
{
"requestId": null,
"success": false,
"errorCode": -1,
"errorId": null,
"data": null,
"message": "IdentityStore does not exist"
}

4.3 组织

4.3.1 新增组织

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/group/add

认证：Basic Auth。

字段 类型 必填 说明
name string 是 用户组名称
identityStoreId string 是 用户源 ID
parentGroupId string 否 父组织 ID；为空时创建根组织
externalGroupId string 否 外部组织 ID
attributes array 否 扩展属性
JSON
{
"name": "研发一组",
"identityStoreId": "<identity-store-id>",
"parentGroupId": "<parent-group-id>"
}

成功响应：

JSON
{
"success": true,
"errorCode": 0,
"message": null
}

4.3.2 获取用户源下全部组织

HTTP
GET {baseUrl}/am/api/admin/tenant/identity/group/list?identityStoreId=<identity-store-id>

认证：Basic Auth。

Query 参数 类型 必填 说明
identityStoreId string 是 用户源 ID

成功响应：

JSON
{
"success": true,
"errorCode": 0,
"data":
\{
"createTime": 1678072180622,
"updateTime": 1678072180622,
"entityVersion": 0,
"id": "\",
"identityStoreId": "\",
"name": "研发部",
"children": \[
\{
"id": "\",
"identityStoreId": "\",
"parentGroupId": "\",
"name": "研发一组",
"children": \[
}
]
}
],
"message": null
}

4.3.3 更新组织

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/group/update

认证：Basic Auth。

字段 类型 必填 说明
id string 是 组织 ID；服务端据此读取现有组织及所属用户源
name string 是 组织名称，不可为空
parentGroupId string 否 新的父组织 ID；为空时移动为根组织
externalGroupId string 否 外部组织 ID
attributes array 否 扩展属性；属性元素包含 name 与 value

identityStoreId 无需传入，服务端会根据 id 查询现有组织并补入所属用户源。父组织必须与

当前组织属于同一用户源，且调用方必须同时具备原父组织与新父组织的写权限。

JSON
{
"id": "<group-id>",
"name": "研发一组",
"parentGroupId": "<parent-group-id>",
"externalGroupId": "<external-group-id>",
"attributes":
\{ "name": "costCenter", "value": "RD" \}

}

成功响应为通用无 data 响应。

4.4 角色

4.4.1 获取站点下所有角色

HTTP
GET {baseUrl}/am/api/admin/tenant/identity/role/list

认证：继承角色目录的父级认证，即 Basic Auth。

Query 参数 类型 必填 说明
tenantId string 是 站点 ID
keyword string 否 搜索关键词
firstResult integer 是 分页起始位置
maxResults integer 是 最大返回数量

成功响应：

JSON
{
"success": true,
"errorCode": 0,
"data":
\{
"createTime": 1787038780000,
"updateTime": 1787038780000,
"entityVersion": 0,
"id": "\",
"tenantId": "\",
"name": "testRole1",
"description": "测试角色",
"fromIdentityStoreId": "\",
"attributes": \[
}
],
"message": null
}

4.4.2 创建角色

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/role/add

认证：继承角色目录的父级认证，即 Basic Auth。

JSON
{
"tenantId": "<tenant-id>",
"role": {
"id": "",
"name": "testRole2",
"fromIdentityStoreId": "<identity-store-id>",
"description": "测试角色",
"attributes": \[\],
"members": \[\],
"tenantId": "<tenant-id>"
}
}
字段 类型 必填 说明
tenantId string 是 站点 ID
role RoleInput 是 角色数据

成功响应的 data 为创建后的角色对象。

4.4.3 更新角色

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/role/update

认证：继承角色目录的父级认证，即 Basic Auth。

JSON
{
"tenantId": "<tenant-id>",
"role": {
"id": "<role-id>",
"tenantId": "<tenant-id>",
"name": "testRole11",
"description": "测试角色",
"fromIdentityStoreId": "<identity-store-id>",
"attributes": \[\],
"members": \[\]
}
}

成功响应：

JSON
{
"success": true,
"errorCode": 0,
"message": null
}

4.5 令牌

4.5.1 用户和令牌的绑定关系

请求： GET /am/rest/p/1/token/binding/list 或 POST /am/rest/p/1/token/binding/list

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
以下两种方式二选一

（1）根据用户登录名，查询该用户绑定的令牌

请求参数 必填 说明
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名

（2）根据令牌序列号，查询该令牌绑定的用户

请求参数 必填 说明
type 是 令牌类型
1：时间令牌
2：短信令牌
serial 是 令牌序列号
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": \[\],
"message": null
}
响应参数 说明
data TokenBinding数组

4.5.2 派发手机令牌

请求： GET /am/rest/p/1/token/mobileToken/deliver 或 POST /am/rest/p/1/token/mobileToken/deliver

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
mode 是 派发模式
0：派发到邮箱
1：派发到手机短信
2：仅绑定
unbindPrevious 是否解绑以前的令牌
默认值true：解绑
toEmail 激活码接收邮箱。如果不填写，激活码发送到用户默认邮箱中；如果用户没有默认邮箱，则必须填写
toMobile 激活码接收手机号。如果不填写，激活码发送到用户默认手机号中；如果用户没有默认手机号，则必须填写
expireInDays 激活码有效期（天）。如果不填写，则按照站点名称所对应站点内配置的激活码有效期为准
tokenExpireInDays 令牌有效期（天）。如果不填写，则按照站点名称所对应站点内配置的激活码有效期为准
tokenBindingStartDelayHours 令牌延迟启用（小时）。如果不填写，则按照站点名称所对应站点内配置的令牌延迟启用为准
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": null,
"message": null
}
响应参数 说明
data 令牌信息，TokenInfo

4.5.3 获取手机令牌二维码

请求： GET /am/rest/p/1/token/mobileToken/userQrCode 或 POST /am/rest/p/1/token/mobileToken/userQrCode

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
响应示例

!4DKEY AM API\.assets/4\.png

4.5.4 绑定并获取手机令牌二维码

请求： GET /am/rest/p/1/token/mobileToken/bindAndWriteMobileTokenQrCode 或 POST /am/rest/p/1/token/mobileToken/bindAndWriteMobileTokenQrCode

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
bindingEnabled 用户和令牌的绑定关系是否有效
默认值false：虽然绑定了，但是是无效的
响应示例

!5DKEY AM API\.assets/5\.png

4.5.5 完成手机令牌绑定

请求： GET /am/rest/p/1/token/mobileToken/completeMobileTokenBinding 或 POST /am/rest/p/1/token/mobileToken/completeMobileTokenBinding

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员登录密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
password 是 令牌动态口令
unbindPrevious 是否解绑以前的手机令牌
默认值false：不解绑
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": null,
"message": null
}

4.5.6 绑定时间型令牌

请求： GET /am/rest/p/1/token/bind 或 POST /am/rest/p/1/token/bind

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
serial 是 令牌序列号
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": null,
"message": null
}

4.5.7 解绑时间型令牌

请求： GET /am/rest/p/1/token/unbind 或 POST /am/rest/p/1/token/unbind

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
serial 是 令牌序列号
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": null,
"message": null
}

4.5.8 解绑所有时间型令牌

请求： GET /am/rest/p/1/token/unbindAll 或 POST /am/rest/p/1/token/unbindAll

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
identityStoreName 是 用户源名称
本地用户源：06bc758e-04f2-40b3-9d6c-562b115aeb3c
外部用户源：和创建的外部用户源名称一致
loginName 是 用户登录名
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": null,
"message": null
}

4.5.9 获取手机令牌信息

请求： GET /am/rest/p/1/token/mobileToken/data 或 POST /am/rest/p/1/token/mobileToken/data

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名称
serial 是 令牌序列号
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": {
"model": 4,
"serial": "000004",
"crypto": 1,
"seed": "7d79cf3815be526b543f9d475ccaf8402f289f27",
"timeStep": 60,
"passwordLength": 6,
"expireTime": 3281827405000
},
"message": null
}
响应参数 说明
model 固定为4，代表手机令牌
serial 令牌序列号
crypto 令牌算法
1：OATH
2：SM3
seed 种子
timeStep 令牌时间步进，单位秒
passwordLength 动态口令长度
expireTime 令牌过期时间

4.6 系统、终端与 MAC 管理

4.6.1 站点列表

请求： GET /am/rest/p/1/tenant/list 或 POST /am/rest/p/1/tenant/list

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
响应示例
JSON
{
"success": true,
"errorCode": 0,
"data": \{
"id": "8de4afd9\-2506\-47e5\-91bf\-30a10596b535",
"name": "测试"
\},
"message": null
}
响应参数 说明
id 站点id
name 站点名称

4.6.2 新增Mac地址黑白名单

请求： GET /am/rest/p/1/identity/blackWhiteMacAddressList/add 或 POST /am/rest/p/1/identity/blackWhiteMacAddressList/add

请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名字
macAddress 是 Mac地址
type 是 1：禁止 2：有效
startDate 有效开始时间毫秒时间戳
endDate 有效结束时间毫秒时间戳
description 描述

tips：有效开始时间与有效结束时间都不填时视为永久

响应示例：

{
"requestId": null,
"success": true,
"errorCode": 0,
"data": null,
"message": null
}

4.6.3 替换Mac地址黑白名单

POST am/rest/p/1/identity/blackWhiteMacAddressList/list/replace
请求参数 必填 说明
adminLoginName 是 管理员登录名
adminPassword 是 管理员密码
tenantName 是 站点名字
macAddressList 是 json字符串对应对象

请求示例

POST am/rest/p/1/identity/blackWhiteMacAddressList/list/replaceadminLoginName=admin&adminPassword=admin

请求体示例

{
"tenantName": "test",
"macAddressList":
\{
"macAddress": "F4:96:34:91:CE:F9",
"type": 2,
"description": "示例终端",
"enablement": \{
"enabled": false,
"startTime": null,
"endTime": null
\}
\},
\{
"macAddress": "00:E0:4C:36:01:44",
"type": 2,
"description": "示例终端",
"enablement": \{
"enabled": false,
"startTime": null,
"endTime": null
\}
\}

}

响应示例

{
"success": true,
"errorCode": 0,
"message": null
}

4.6.4 获取 MAC 列表集

HTTP
GET {baseUrl}/am/api/admin/tenant/identity/macList/list

认证：Basic Auth。

Query 参数 类型 必填 说明
tenantId string 是 站点 ID
firstResult integer 是 分页起始位置
maxResults integer 是 最大返回数量

成功响应的 data 为分页对象：startRow、totalCount、data\[\]；列表集元素包含

id、tenantId、name、createTime、updateTime、entityVersion。

4.6.5 获取终端 MAC 地址列表

HTTP
GET {baseUrl}/am/api/admin/tenant/identity/macList/macItem/list
Query 参数 类型 必填 说明
macListId string 是 MAC 列表集 ID
firstResult integer 是 分页起始位置
maxResults integer 是 最大返回数量

成功响应为分页对象。

4.6.6 新增 MAC 列表集

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/macList/add
JSON
{
"tenantId": "<tenant-id>",
"name": "列表集名称",
"description": ""
}

4.6.7 编辑 MAC 列表集

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/macList/update

请求体在新增结构基础上增加必需的列表集 id；tenantId 应保持为原列表集所属站点。

JSON
{
"tenantId": "<tenant-id>",
"id": "<mac-list-id>",
"name": "列表集名称",
"description": ""
}

4.6.8 删除 MAC 列表集

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/macList/delete
JSON
{
"id": "<mac-list-id>"
}

4.6.9 新增终端 MAC

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/macList/macItem/add
JSON
{
"macListId": "<mac-list-id>",
"macAddress": "AA:AA:AA:BB:BB:BB",
"description": ""
}

4.6.10 编辑终端 MAC

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/macList/macItem/update

请求体字段：终端记录 id（必填）、macAddress（必填）、description（可选）。所属 macListId 由服务端按现有记录确定。

4.6.11 删除终端 MAC

HTTP
POST {baseUrl}/am/api/admin/tenant/identity/macList/macItem/delete

请求体仅需终端记录 id；站点与所属列表集由服务端按现有记录确定。

4.6.12 根据关键字查询 MAC 列表项

HTTP
GET {baseUrl}/am/api/admin/tenant/identity/macList/macItem/search
Query 参数 类型 必填 说明
tenantId string 是 站点 ID
macListId arraystring 否 MAC 列表集 ID 列表；为空时搜索站点全部列表集
keyword string 是 搜索关键字
firstResult integer 是 分页起始位置
maxResults integer 是 最大返回数量

成功响应的 data.data\[\] 元素包含 id、macListId、macAddress、description、

createTime、updateTime 和 entityVersion。

以上新增、编辑和删除接口均继承 Basic Auth。成功响应均为：

JSON
{
"success": true,
"errorCode": 0,
"message": null
}

5. 数据结构

5.1 UserInfo

JSON
{
"userId": "f5e85d18-d126-4083-ab9d-d87ff7c1d101",
"personalName": "",
"loginName": "0",
"mobiles": \[\],
"email": null,
"groupPath": "a/b/c",
"roles": \[\],
"enabled": true,
"startTime": null,
"endTime": null,
"number": null,
"idCardNumber": null,
"department": null,
"company": null,
"customAttributes": \{
"name": "IP",
"value": "127\.0\.0\.1"
\}
}
响应参数 类型 说明
userId String 用户ID
personalName String 姓名
loginName String 登录名
mobiles String数组 手机号
email String 邮箱
groupPath String 用户组，组与组织间使用/分隔
roles String数组 角色
enabled Boolean 是否启用
startTime 时间戳，毫秒 有效期，起始时间
endTime 时间戳，毫秒 有效期，结束时间
number String 工号
idCardNumber String 身份证号
department String 部门
company String 公司
customAttributes 数组 自定义属性
name：属性名称String
value：属性值String

5.2 TokenInfo

JSON
{
"type": 1,
"model": 4,
"serial": "000015",
"expireTime": 3275184982695
}
响应参数 类型 说明
type int 1：时间令牌
2：短信令牌
model int type=1时：
2：硬件令牌
4：APP手机令牌
type=2时：
1：短信令牌
serial String 令牌序列号如果是短信令牌，则是手机号
expireTime 时间戳，毫秒 令牌到期时间

5.3 TokenBinding

JSON
{
"id": "508b6052-0655-48d1-ae83-8f30a43ba045",
"bindingEnabled": true,
"startTime": 1579062850000,
"priority": 0,
"user": {
......
},
"token": {
......
}
}
响应参数 类型 说明
id String 绑定关系id
bindingEnabled Boolean 绑定关系是否是有效的
startTime 时间戳，毫秒 绑定关系生效的开始时间
priority int 优先级
user UserInfo 用户信息
token TokenInfo 令牌信息

5.4 UserInput

字段 类型 必填 说明
userId string 否 用户 ID；更新或同步时按业务需要传入
externalUserId string 是 外部用户 ID
loginName string 是 登录名
personalName string 否 姓名
userPrincipalName string 否 用户主体名称
alias string 否 别名
password string 否 用户密码
mobile string 否 手机号，与 mobiles 二选一
mobiles arraystring 否 手机号列表
email string 否 邮箱
role string 否 角色名称，与 roles 二选一
roles arraystring 否 角色名称列表
groupPath string 否 组织路径
groupId string 否 组织 ID
enabled boolean 否 是否启用
startTime integerint64 否 生效时间，Unix 毫秒时间戳
endTime integerint64 否 失效时间，Unix 毫秒时间戳
locked boolean 否 是否锁定
unlockTime integerint64 否 解锁时间，Unix 毫秒时间戳
passwordUpdateTime integerint64 否 密码更新时间，Unix 毫秒时间戳
changePasswordAtNextLogin boolean 否 下次登录时是否修改密码
idCardNumber string 否 身份证号
number string 否 工号
department string 否 部门
company string 否 公司
title string 否 岗位
createTime integerint64 否 创建时间，Unix 毫秒时间戳
updateTime integerint64 否 更新时间，Unix 毫秒时间戳
customAttributes arrayCustomAttribute 否 扩展属性

5.5 CustomAttribute

字段 类型 必填 说明
name string 是 属性名
value string 否 字符串值
type integer 否 1=string，2=boolean，3=long
booleanValue boolean 否 布尔值
longValue integerint64 否 长整型值

5.6 RoleInput

字段 类型 必填 说明
id string 更新时是 角色 ID
tenantId string 是 站点 ID
name string 是 角色名称
description string 否 角色说明
fromIdentityStoreId string 否 来源用户源 ID
attributes array 否 扩展属性
members array 否 角色成员

5.7 MacList

字段 类型 说明
id string MAC 列表集 ID
tenantId string 站点 ID
name string 列表集名称
description string 说明
createTime integerint64 创建时间，Unix 毫秒时间戳
updateTime integerint64 更新时间，Unix 毫秒时间戳
entityVersion integer 实体版本

5.8 MacItem

字段 类型 说明
id string 终端记录 ID
macListId string 所属 MAC 列表集 ID
macAddress string MAC 地址
description string 说明
createTime integerint64 创建时间，Unix 毫秒时间戳
updateTime integerint64 更新时间，Unix 毫秒时间戳
entityVersion integer 实体版本

5.9 TacacsAuthLog

字段 类型 说明
id string 日志 ID
tenantId string 站点 ID
loginName string 登录名
terminalIp string 终端 IP
accessServerName string 设备名称
accessServerIp string 设备 IP
accessServerId string 设备 ID
accessServerBrand string 设备品牌
command string 命令
privilegeLevel string 权限级别
result integer 1 成功，0 失败
recordType integer 记录类型
createTime integerint64 创建时间，Unix 毫秒时间戳
createTimeInMicroseconds integerint64 创建时间，微秒精度

5.10 LoginSession

登录会话对象由 AccessSessionInfo.toJson\(\) 生成，并由列表接口补充用户源名称与已通过令牌。

完整返回还可包含嵌套的 tenant、user、accessServer、accessRealm、AP、IP 段及扩展信息。

字段 类型 说明
sessionId string 会话 ID
type integer 登录类型
state integer 会话状态
tenantId string 站点 ID
tenantName string 站点名称
identityStoreId string 用户源 ID
identityStoreName string 用户源名称
userId string 用户 ID
userIdentity string 用户身份
userLoginName string 用户登录名
terminalIp string 终端 IP
terminalMac string 终端 MAC
accessServerName string 接入设备名称
accessRealmId string 认证域 ID
portalTypeUuid string 登录方式标识，即请求筛选参数 signonType 对应值
portalType string 登录方式显示名称
encodedTokens string 已通过令牌序列号，以分号分隔
cLoginTime integerint64 登录时间
cLastActiveTime integerint64 最后活跃时间
messages arraystring 会话消息

6. 统一错误码说明

业务结果通过响应体中的 success 和 errorCode 判断：

  1. success=true 且 errorCode=0：成功。

  2. success=true 且 errorCode!=0：部分成功或需要进一步处理。

  3. success=false：失败，具体原因以 errorCode 和 message 为准。

errorCode 常量 说明
1 OUT_OF_SYNC 不同步
0 SUCCESS 成功
10002 - 登录不被允许
10005 - 用户没有绑定令牌，禁止登录
-1 NOT_EXIST 不存在
-2 DUPLICATE 重复
-3 INVALID_ARGUMENT 无效的参数
-4 NOT_PERMITTED 不允许
-5 CANNOT_COMPLETE_OPERATION 无法完成操作
-6 SYSTEM_ERROR 系统错误
-7 VERSION_NOT_SUPPORTED 版本不支持
-8 BAD_REQUEST 错误的请求
-9 CONNECTION_ERROR 连接错误
-10 ILLEGAL_STATE 非法状态
-11 INVALID_BINDING 无效的绑定
-12 OPERATION_NOT_SUPPORTED 不支持的操作
-13 LICENSE_ERROR 证书错误
-14 ILLEGAL_IDENTITY 非法身份
-15 INVALID_TICKET 无效的票证
-16 INCORRECT_LOGIN_NAME_OR_PASSWORD 登录名或密码错误
-17 USER_LOCKED 用户锁定
-170 TERMINAL_LOCKED 终端锁定
-19 USER_PERMANENT_LOCKED 用户永久锁定
-190 TERMINAL_PERMANENT_LOCKED 终端永久锁定
-21 PASSWORD_INVALID 无效的密码
-2101 DYNAMIC_PASSWORD_ERROR 动态密码错误
-2102 DYNAMIC_PASSWORD_INVALID 动态密码无效
-22 LOGON_NOT_ALLOWED_AT_THIS_TIME 当前不允许登录
-23 LOGIN_NOT_ALLOWEB_ON_THIS_WORKSTATION 此站点不允许登录
-24 USER_MUST_RESET_PASSWORD 用户必须重置密码
-25 USER_PASSWORD_EXPIRED 用户密码已过期
-26 PORTAL_TERMINAL_AUTHORITY_EXCEEDED portal终端超出授权
-27 SSO_ERROR 单点登录错误
-28 AUDIT_PROXY_ERROR 审计代理错误
-29 IDP_NOT_REGISTER 身份提供商未注册
-30 ACTIVATION_CODE_REUSE 激活码重复使用
-31 INVALID_CONFIG 无效的配置
-32 PUSH_AUTH_REJECT 推送认证拒绝
-33 IP_BLOCKED IP被封锁
-34 SESSION_TIMEOUT 会话超时
-35 PUSH_AUTH_ERROR 推送认证错误
-36 REJECTED_EXECUTION 拒绝执行
-37 AUTHENTICATION_TIMEOUT 身份验证超时
-38 USER_IS_NULL 无此用户
-39 LICENSE_EXCEEDED 授权超出
-40 QUOTA_EXCEEDED 配额超出
-41 RATE_LIMITING 限流中
-42 AUTH_NOT_PERMITTED 认证功能权限受限
-43 INCOMPLETE_SUCCESS 不完全成功
-1001 USER_IS_DISABLED 用户已禁用
-1002 USER_PASSWORD_REUSE_EXCEEDS_SETTING 密码重用超过设定次数
-1003 USER_IS_EXPIRED 用户已过期
-2001 CAPTCHE_NULL 验证码为空
-2002 CAPTCHE_ERROR 验证码错误
-2003 CAPTCHE_EXPIRED 验证码过期
-2103 NOT_MATCH_PASSWORD_CONDITION 不满足密码条件
-2104 CONFIRM_PASSWORD_ERROR 确认密码错误
-3001 INVALID_INTERFACE 无效的接口
-3002 INVALID_FILTER 无效的过滤器
-4001 INVALID_MOBILE_TOKEN 已失效的手机令牌
-4002 ACTIVATION_CODE_ILLEGAL 已过期或失效的手机令牌激活码
-10001 DELETE_ERROR_REFERENCED_BY_OTHER_MODULE 删除失败，被其他模块引用
-5001 DELETE_CONFIRM 删除确认
-7001 USER_SELF_REGISTER_SUCCESS_BUT_NOTIFY_FAILED 用户自注册成功，但通知失败
-10000 NDA_GENERATE_SIGN_FAILED 生成签名失败（鉴权第一步，在UC上面生成签名）
-10001 NDA_REPEAT_NONCE nonce重放攻击保护
-10002 NDA_TIME_DIFF_TOO_LONG 时间差过大
-10003 NDA_APP_NOT_FOUND 应用未找到（鉴权第二步，请求获取UserCode，根据appId查找app）
-10004 NDA_VERIFY_SIGN_FAILED 签名验证失败（鉴权第二步，请求获取UserCode，验证签名）
-10005 NDA_USER_CERT_NOT_EXIST 用户证书不存在（鉴权第二步，请求获取UserCode，查找用户证书）
-10006 NDA_USER_CERT_SIGN_FAILED 用户证书签名失败（鉴权第二步，请求获取UserCode，使用用户证书签名失败）
-10007 NDA_USER_CERT_NOT_EXIST_AM 用户证书不存在（鉴权第三步，UserCode换取UserInfo，通过证书序列号查找证书）
-10008 NDA_USER_CERT_TO_USERID_FAILED_AM 用户证书解析userId失败（鉴权第三步，UserCode换取UserInfo，通过用户证书解析userId）
-10009 NDA_VERIFY_SIGN_FAILED_AM 签名验证失败（鉴权第三步，UserCode换取UserInfo，验证用户证书签名）
-10010 NDA_FIND_USER_FAILED_AM 查找用户失败（鉴权第三步，UserCode换取UserInfo，通过userId查找用户失败）
-10011 NDA_DECODE_USER_CODE_FAILED_AM 解析userCode失败（鉴权第三步，UserCode换取UserInfo，解析userCode失败）
-10012 NDA_DECODE_USER_CERT_FAILED_AM 解析用户证书失败（鉴权第三步，UserCode换取UserInfo，解析用户证书失败）
-10013 NDA_DOMAIN_USER_NOT_EXISTED 域用户不存在（鉴权第二步，请求获取UserCode，判断域用户是否登录）
-10014 NDA_MULTIPLE_LOGIN_USER 解析用户证书失败（鉴权第二步，请求获取UserCode，判断是否存在多个登录用户）
-10015 NDA_COMPUTER_NOT_EXIST 计算机不存在（鉴权第三步，UserCode换取UserInfo，查找计算机）
-10099 NDA_FIND_USER_BY_USER_CODE_FAILED_AM UserCode换取UserInfo失败，未知错误（鉴权第三步，UserCode换取UserInfo）
-20010 UPSTREAM_TASKS_SYNCHRONIZING 上游任务正在进行中
-20020 DOWNSTREAM_TASKS_SYNCHRONIZING 下游任务正在进行中
-20030 OPERATION_TOO_FREQUENT 操作太过频繁
-20040 SYNCHRONIZATION_TASK_IN_PROGRESS 有同步任务正在进行中
-30000 ADMIN_APPROVAL_MATCHED 操作需要审批，已经加入到审批记录表
-30001 ADMIN_APPROVAL_LOG_ERROR 生成的审批记录有误
-30002 ADMIN_APPROVAL_LOG_NOT_EXISTED 审批记录不存在
-30003 ADMIN_APPROVAL_LOG_STATE_ERROR 审批记录的审批状态不对
-30004 ADMIN_APPROVAL_REPEAT 重复审批审批对所有管理员生效，其他授权管理员已经审批过了
-30005 ADMIN_APPROVAL_NO_PERMISSION 没有审批权限接口调用错误，这条审批记录不该自己审批
-30006 ADMIN_APPROVAL_ADD_ERROR 审批新增操作，保存到数据库出现了异常
-30007 ADMIN_APPROVAL_UPDATE_ERROR 审批更新操作，保存到数据库出现了异常
-30008 ADMIN_APPROVAL_DELETE_ERROR 审批删除操作，保存到数据库出现了异常
-10001 和 -5001 均存在一个码值对应多个业务语义的情况，使用方应结合接口业务域与

message 判断，不应仅按数值映射固定文案。

附录 A：目录说明

本附录概述各接口目录的业务用途，完整参数与示例以第 4 章为准。

A.1 认证、日志与会话

  • 完成用户身份认证、认证策略查询和动态密码发送。

  • 查询 TACACS+ 认证日志、审计日志及用户登录会话。

A.2 用户

  • 同步、添加、更新、删除和查询用户信息。

  • 管理用户终端绑定关系并申请临时用户。

A.3 组织

  • 新增、查询和更新组织，支持父子层级结构。

A.4 角色

  • 查询站点角色，创建或更新角色。

A.5 令牌

  • 查询用户与令牌绑定关系。

  • 派发、绑定、解绑和查询手机令牌或时间型令牌。

A.6 系统、终端与 MAC 管理

  • 查询站点列表并管理 MAC 地址黑白名单。

  • 查询、新增、编辑和删除 MAC 列表集及其中的终端 MAC。

附录 B：安全说明

  1. 所有生产调用必须使用 HTTPS。

  2. 管理员密码、用户密码、共享密钥不得写入日志、错误信息或版本库。

  3. Query 中传递密码可能进入代理日志和访问日志，应优先使用请求头或请求体传递敏感信息。

  4. Basic Auth 仅是编码而非加密，必须与 TLS 配合使用。

  5. 调试示例应使用占位值，不得复用生产账号或真实个人信息。

最近修改: 2026-10-22Powered by