API 认证

智穗 Frp 开放 API 供桌面端、脚本与自动化工具调用。除浏览器登录态外，自动化应使用 Personal Access Token（PAT）。

智穗 Frp 开放 API 供桌面端、脚本与自动化工具调用。除浏览器登录态外，自动化应使用 Personal Access Token（PAT）。

创建 PAT

控制台 → 设置 → API 令牌
创建令牌，填写名称（如 deploy-script）
复制 zsfrp_pat_... —— 明文仅显示一次

📷 图片占位 /images/docs/api/create-pat.png
建议内容：创建成功对话框与复制按钮。

桌面端 设置 → API 令牌 亦可管理，与控制台账号同步。

请求格式

Authorization: Bearer zsfrp_pat_xxxxxxxx
Content-Type: application/json

curl 示例：

curl -s -H "Authorization: Bearer zsfrp_pat_xxx" 
  https://你的域名/api/v1/tunnels

响应格式

{
  "code": 0,
  "message": "ok",
  "data": { }
}

code !== 0 时 message 为错误说明。

PAT 能力范围

能力	说明
隧道 CRUD	列表、创建、更新、删除
隧道操作	启用/禁用、克隆、批量、诊断
Launch Link	一键启动链接
节点	推荐节点（需认证）
流量	隧道流量统计

PAT 不能访问管理员接口。

HTTP 状态码

状态	含义
401	未提供、无效或已吊销 Token
403	无权限
429	请求过频（公开接口有限流）

安全规范

勿提交到 Git、勿截图公开
按用途分令牌，不用即吊销
泄露后立即删除并新建
服务器脚本用环境变量：export ZSFRP_PAT=zsfrp_pat_xxx

脚本示例（创建并启动）

API=https://你的域名
TOKEN=zsfrp_pat_xxx

# 推荐节点
curl -s -H "Authorization: Bearer $TOKEN" 
  "$API/api/v1/nodes/recommend?protocol=tcp"

# 创建隧道（示例）
curl -s -X POST -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"name":"auto-1","nodeId":1,"type":"tcp","localAddr":"127.0.0.1:8080"}' 
  "$API/api/v1/tunnels"