外观
API 认证与只读示例
面向需要程序化访问的维护者。本页不是冻结的完整 API 合约;写操作结构以当前版本处理器/接口返回为准。先使用只读请求验证认证与权限。
令牌类型
| 类型 | 权限与用途 |
|---|---|
| 登录会话 | 对应当前账号及会话有效期 |
| 个人 API 令牌 | 解析为实际用户,权限随账号及服务范围校验 |
| 全局 API 令牌 | 管理能力较高,仅用于可信集成 |
| Agent/服务器令牌 | 用于 Agent 接入,不当作用户会话使用 |
| 订阅令牌 | 获取特定订阅,不是管理 API 通行证 |
不要把“请求路径含 admin”当作权限判断的唯一依据;部分兼容路径供普通用户使用,但处理器仍限制资源范围。反过来,拥有个人令牌也不代表有全部管理权限。
请求头
使用 HTTPS,将令牌放入头:
http
Authorization: Bearer YOUR_TOKEN会话认证不使用 ?token= 查询参数,以减少 URL、访问日志和 Referer 泄露。代理不应记录完整 Authorization 头。
只读示例
下面 Bash 示例交互读取令牌,避免直接写入 shell 历史;结束后清理变量。令牌仍在当前进程环境中,应在可信主机上执行。
bash
read -rsp 'API token: ' RELAYDOCK_TOKEN
printf '\n'
curl --fail-with-body --connect-timeout 10 \
-H "Authorization: Bearer $RELAYDOCK_TOKEN" \
https://panel.example.com/api/user/profile
unset RELAYDOCK_TOKEN常见只读入口:
| 路径 | 用途 / 权限 |
|---|---|
GET /api/setup/status | 是否需要初始化,不用于管理业务数据 |
GET /api/public/branding | 公开品牌配置 |
GET /api/public/oauth/providers | 公开可用登录方式 |
GET /api/user/profile | 当前账号资料,需要认证 |
GET /api/admin/remote-servers | 服务器列表,需要管理员 |
GET /api/admin/nodes | 节点列表,需要认证并受账号范围限制 |
使用非管理员令牌测试管理接口应得到拒绝,不要为了让脚本成功而扩大账号权限。
错误响应与处理
| 状态 | 典型含义 | 客户端处理 |
|---|---|---|
| 400 | 参数、格式或业务校验失败 | 展示具体原因,修正输入 |
| 401 | 缺少/无效/过期认证 | 重新认证,不循环重试 |
| 403 | 账号停用、权限或范围不允许等 | 展示拒绝原因,不自动升级权限 |
| 404 | 路径或资源不存在,也可能版本不匹配 | 核对版本与资源 |
| 409 | 并发状态或业务冲突等 | 读取最新状态后人工决定 |
| 429 | 频率限制 | 等待,按响应约定退避 |
| 5xx | 后端、远端执行或网关异常 | 记录请求阶段与日志,区分是否已执行 |
HTTP 200 也要检查响应体中的逐项结果和警告,不能只看状态码判断批量全部成功。
写接口的约束
创建、删除、切换目标和更新等请求不要在超时后盲目重复。先读取当前状态,确认幂等支持、并发版本和远端确认结果。不要根据这份示例绕过网页校验直接修改数据库。
自动化集成应固定匹配版本、处理撤销和过期,并测试普通用户、停用用户与资源越权场景。
