认证

Tapilot 有两层认证:

• MCP(stdio) — 无需认证,本地进程通信
• HTTP REST API — 需要 Bearer Token 或 API Key

MCP 无需认证

Claude Code / Cursor 通过 stdio 启动 npx -y mobai-mcp,是本地子进程,不走网络,没有认证概念。

⚠️ 注意:MCP server 有访问你所有设备的能力(可截屏、可点击、可输入)。别把 MCP server 暴露给不可信的 AI 或远程客户端。

HTTP API 认证

所有受保护端点(除 GET / 等公开端点外)需要请求头:

Authorization: Bearer <JWT_TOKEN>

或:

X-API-Key: <API_KEY>

获取 Token / API Key

1. 自建部署(开源版)

启动 HTTP server:

npx mobai-api
# 默认监听 0.0.0.0:3210

默认无需认证(开发模式)。生产启用认证:

MOBAI_AUTH_ENABLED=true \
MOBAI_API_KEYS='key1,key2,key3' \
npx mobai-api

2. 云端账号(tapilot.dev)

1. 访问 https://app.tapilot.dev 注册
2. 控制台 → API Keys → 创建
3. 复制 key(只显示一次),放到环境变量:

export TAPILOT_API_KEY=sk_live_xxx

请求示例

curl

curl -H "Authorization: Bearer $TAPILOT_API_KEY" \
  https://app.tapilot.dev/api/devices

JavaScript (fetch)

const resp = await fetch("https://app.tapilot.dev/api/devices", {
  headers: { Authorization: `Bearer ${process.env.TAPILOT_API_KEY}` }
});
const devices = await resp.json();

Python

import os, requests
headers = {"Authorization": f"Bearer {os.environ['TAPILOT_API_KEY']}"}
r = requests.get("https://app.tapilot.dev/api/devices", headers=headers)
print(r.json())

用量限制

计划	限流	月度请求上限
Free	60 req/min	10,000
Pro	600 req/min	200,000
Enterprise	自定义	自定义

超限返 429 Too Many Requests,header 带 Retry-After 指示等待秒数。

Auth 端点特殊限流:/api/auth/* 固定 10 req/min(防暴力破解)。

错误响应

所有错误格式:

{
  "error": "invalid_token",
  "message": "JWT expired at 2026-04-22T12:00:00Z"
}

常见错误:

HTTP 状态	错误码	说明
401	missing_token	未带 Authorization 头
401	invalid_token	token 过期 / 签名错
403	forbidden	token 有效但无权访问该资源(plan 限制)
429	rate_limited	超过限流
402	payment_required	Free 计划超出月度上限

CORS

默认白名单:https://tapilot.dev、https://app.tapilot.dev、tauri://localhost。

自建部署通过 CORS_ORIGINS 环境变量扩:

CORS_ORIGINS='https://yourapp.com,https://staging.yourapp.com'

安全建议

• API Key 只放环境变量 / Secret Manager,永远不要 commit 到代码
• Web 前端不要直接持有 API Key,通过你自己的后端代理调用
• 定期轮换(控制台 → API Keys → Rotate)
• 看到可疑调用立即 Revoke