Skip to content

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 也要检查响应体中的逐项结果和警告,不能只看状态码判断批量全部成功。

写接口的约束 ​

创建、删除、切换目标和更新等请求不要在超时后盲目重复。先读取当前状态,确认幂等支持、并发版本和远端确认结果。不要根据这份示例绕过网页校验直接修改数据库。

自动化集成应固定匹配版本、处理撤销和过期,并测试普通用户、停用用户与资源越权场景。

操作示例与截图均使用演示数据 · 内容核对于 2026-11-20