代理面板 API 凭据登录对接文档

使用 API 凭据中的 key 和 secret 换取会话 token，随后通过 access-token 请求头调用业务接口。普通账户对接使用 POST /user/login；持有管理员系统 API 凭据时使用 POST /admin/login，并额外发送 api-access: 1。

接口选择与准备

BASE_URL 表示代理面板 API 的根地址，例如 https://panel.example.com。下文接口路径均相对于该地址，完整请求地址以面板管理员提供的 API 根地址为准。

凭据种类	登录接口	登录时的 api-access 请求头	成功响应的 type	业务接口范围
用户 API 凭据	`POST /user/login`	不发送	`user`	`/user/...`，受账户资源范围限制
管理员系统 API 凭据	`POST /admin/login`	`1`	`admin`	`/admin/...`，受管理员权限限制

由面板管理员提供对应类型的 key、secret，并确认凭据所属账户可用。如果设置了 IP 白名单，登录请求的出口 IP 必须已获授权。

用户 API 凭据登录

请求定义

请求体参数	必填	类型	说明
`key`	是	string	用户 API 凭据的 Key
`secret`	是	string	同一条 API 凭据的 Secret

key 和 secret 必须同时填写且不能为空。若返回“用户名或密码错误”，也应先确认这两个 API 凭据字段是否完整、正确。

API 登录只需提交 key 和 secret，无需用户名、密码或动态口令。用户 API 登录不发送 api-access 请求头。

表单调用示例

将示例地址、Key 和 Secret 替换为实际值：

也可以提交 JSON，请求头与请求体对应如下：

成功响应

HTTP 状态码为 200：

{
  "success": true,
  "token": "0123456789abcdef0123456789abcdef01234567",
  "ttl": "1800",
  "type": "user"
}

示例 Token 为占位值。

响应字段	类型	说明
`success`	boolean	`true` 表示登录成功
`token`	string	后续接口使用的会话令牌，按不透明字符串保存
`ttl`	string 或 number	允许闲置的秒数，接入方按数值解析；实际值取决于系统配置
`type`	string	用户 API 为 `user`；管理员系统 API 为 `admin`

使用 Token 调用业务接口

登录成功后，后续请求统一发送以下请求头：

例如读取当前账户可访问的服务器列表：

access-token 的值就是登录返回的 token，不加 Bearer 前缀。不要改成 Authorization: Bearer ...、普通会话的 token 请求头、Cookie 或 URL 参数，也不要同时发送 token 和 access-token。请求头使用不正确时，可能返回“请重新登录”。

后续业务请求不需要重复提交 key、secret；管理员登录使用的 api-access 请求头也不需要继续发送。

用户 API 默认访问本账户资源。如需访问关联账户资源，请由面板管理员为该凭据开通相应授权。访问范围以管理员分配的账户及资源授权为准。

有效期与重新登录

ttl 表示会话允许闲置的秒数，以登录响应中的实际值为准。例如 1800 表示允许闲置 30 分钟。

会话按闲置时长过期：每次通过业务接口鉴权后重新计算闲置时长，连续闲置超过规定时长后失效。

令牌过期后，重新调用相应登录接口，使用原来的 key、secret 获取新令牌。接口不提供独立的令牌刷新或注销操作。删除 API 凭据后，已有令牌也无法继续通过鉴权。

接入方应同时检查 HTTP 状态码和 JSON 响应：

HTTP 为 2xx 且 success 为 true，才按接口成功处理。

出现 auth_error: true 或 HTTP 401 时，检查请求头并清除缓存令牌；确认属于过期或失效后，重新登录一次。

“用户已禁用”、凭据错误、IP 不允许或权限不足需要修正配置，不应循环重新登录。

网络超时或 5xx 时，对重装、删除等写操作先核实执行结果，避免重复提交。明确被前置鉴权拒绝的请求，可在重新登录成功后重试一次。

失败响应与排查

登录失败通常返回：

{
  "success": false,
  "error": "key or secret error"
}

业务接口发现令牌失效时，可能仍返回 HTTP 200：

{
  "success": false,
  "error": "凭据过期",
  "auth_error": true
}

场景	HTTP 状态码	error 或标志	接入处理
Key 或 Secret 错误、凭据类型不匹配、所属账户不存在	`403`	`key or secret error`	核对凭据、登录路径和 `api-access` 请求头
登录来源 IP 不在凭据白名单	`403`	`access denied`	核对服务端识别到的出口 IP 和白名单
必填字段缺失或为空	`403`	字段校验错误，可能为“用户名或密码错误”	确认同时发送非空的 `key`、`secret`
凭据与登录路径不匹配	`403`	`用户名或密码错误`	用户凭据走 `/user/login`，系统凭据走 `/admin/login`
登录失败次数过多	`400`	`登陆错误次数过多, 稍后再试`	停止自动重试，核对凭据后稍后再试
业务请求缺少、无效或过期令牌，或凭据已删除	通常 `200`	`凭据过期`，`auth_error: true`	检查令牌与凭据状态，必要时重新登录
API 令牌请求头使用不正确，或会话需要重新登录	`401`	`请重新登录`，`auth_error: true`	使用 `access-token`，重新获取令牌
所属用户账户已禁用	`403`	`用户已禁用`，`auth_error: true`	联系管理员恢复账户状态
后续业务接口权限不足	`400` 或 `403`	如 `拒绝访问` 等	核对账户权限及资源授权

管理员系统 API 凭据登录

仅在持有管理员创建的系统 API 凭据时使用。需要同时满足以下条件：请求路径为 /admin/login，请求头带 api-access: 1，请求体使用系统 API 的 key、secret。

成功响应结构与用户 API 相同，type 为 admin。后续调用 /admin/... 时仍使用 access-token: LOGIN_RESPONSE_TOKEN，并受凭据所属管理员的用户组权限限制。

API 登录无需提交动态口令。若面板启用管理员强制绑定双因素验证，而凭据所属管理员尚未绑定，后续部分管理接口仍会返回 HTTP 400、otp_required: true、error: "请添加双因素验证"，需要先由管理员完成绑定。

代理面板 API 凭据登录对接文档

接口选择与准备#

用户 API 凭据登录#

请求定义#

表单调用示例#

成功响应#

使用 Token 调用业务接口#

有效期与重新登录#

失败响应与排查#

管理员系统 API 凭据登录#